# Patch Image

Partially updates an existing image identified by its filename (reference), which is unique per tenant — substitute its file via a new url and/or replace its tags. At least one of these fields must be supplied.
            
The filename at the end of the replacement url must be exactly the image's current reference —
same name and same extension (compared case-sensitively). Anything else is rejected with 400 and the
image is left untouched.
            

PATCH /images(product-123.jpg)
{ "url": "https://cdn.example.com/products/v2/product-123.jpg" }   OK   same filename
{ "url": "https://cdn.example.com/products/product-123-v2.jpg" }   400  different name
{ "url": "https://cdn.example.com/products/product-123.png" }      400  different file type

            
### Replacing an image with a differently named file today
            
While the limitation is in force, do it client-side in three steps:
            
1. Create the new image — POST /images with the new file's url.
2. Repoint the references — use the Catalog API to find every entity (product, variant, category, …)
   that uses the old filename and update it to the new one.
3. Delete the old image — DELETE /images({old-reference}) once nothing references it any more.
            
## Fields
            
- url (optional): public URL of the new image. Triggers a full image substitution. Must end in the
  image's current filename — see the temporary limitation above.
- tags (optional): array of strings, validated exactly as on POST /images.
  - Absent, and url not supplied either → tags are not modified.
  - Absent, url also supplied → all tags are cleared (legacy behaviour: substituting the
    image file wipes its tags unless you resend them in the same request).
  - [] → all tags are cleared.
  - ["a","b"] → tags are replaced with these values.
            
## Valid combinations
            
| Body | Operation |
|------|-----------|
| { "url": "https://.../{same-filename}" } | Substitute image — clears existing tags |
| { "url": "https://.../{same-filename}", "tags": ["a"] } | Substitute image and set tags |
| { "tags": ["a"] } | Update tags only, image file unchanged |
            
## Invalid combinations
            
- Empty body {} → 400.
- url whose filename differs from the image's reference → 400 (see the temporary limitation above).
            
## Response (204 No Content)
            
Success returns no body.
            
## Notes
            
- If the image is currently being processed, returns 409.
- A substitution resets the image's status to Up and re-enqueues it for processing, so the
  thumbnails are regenerated. Until the worker finishes, GET /images({reference}) reports Up
  and the rendition URLs still point at the previous file. Poll status for Ok (or Er) before
  treating the new file as live.
- A tags-only update does not touch status and takes effect immediately.
- Either way modifiedOn is refreshed.
- A substitution does not change the image's reference, so entities referencing it keep working.
            
## Error Responses
            
- 400 Bad Request: Invalid request body (e.g., both fields missing), a replacement url whose
  filename is not the image's current reference, or any of the url/tags validation failures
  documented on POST /images (format, accessibility, Content-Type, size, dimensions). Same
  { "validationFailures": { "error": [...] } } envelope
- 401 Unauthorized: Missing or invalid API key. Returned by the API gateway as
  { "message": "Unauthorized", "request_id": "d8aafa5b8f3e400b60bea0123dd33317" }
- 403 Forbidden: The API key does not have write permissions for this operation. Same body
  shape as the 401
- 404 Not Found: No image with the given reference exists for this tenant. The body is the
  message string, e.g. "Image with reference 'missing.jpg' not found"
- 409 Conflict: The image is currently being processed and cannot be modified —
  { "error": "Image 'product-123.jpg' is currently being processed and cannot be modified" }
- 500 Internal Server Error: Technical error (network failure fetching the replacement file,
  storage or database unavailable). The already-uploaded replacement object is cleaned up, so the
  image is left on its previous file

Endpoint: PATCH /images({reference})
Version: 2.0.0

## Header parameters:

  - `X-API-KEY` (string, required)
    Tenant's API key (required)

## Path parameters:

  - `reference` (string, required)
    Image filename (reference), unique per tenant (e.g. product-main-front.jpg)

## Request fields (application/json):

  - `reference` (string,null)
    Taken from the URL path, not from the request body — any value sent in the body is ignored.

  - `url` (string,null)
    Publicly accessible URL of the replacement image, which triggers a full substitution. Optional,
but at least one of url or tags must be supplied. Validated exactly as on create,
and it must end in the image's current filename — renaming an image is not supported yet.

  - `tags` (array,null)
    Tags to set on the image. Optional. Omit to leave the tags untouched, send [] to clear them,
or send values to replace them. Note that omitting this field while substituting the image via
url clears the tags.

## Response 400 fields (application/json):

  - `validationFailures` (object,null)

## Response 401 fields (application/json):

  - `message` (string,null)
    Error description, e.g. Unauthorized.

  - `request_id` (string,null)
    Gateway request identifier, to quote when contacting support.

## Response 403 fields (application/json):

  - `message` (string,null)

  - `request_id` (string,null)

## Response 409 fields (application/json):

  - `error` (string,null)

## Response 500 fields (application/json):

  - `error` (string,null)

  - `details` (any,null)


## Response 204 fields