---
title: "Update an image metadata entry"
method: PUT
path: "/images/{image_id}"
tags: ["image"]
---

# Update an image metadata entry

`PUT /images/{image_id}`

Updates an existing image metadata entry whose id matches the id provided as path parameter. Only the provided fields will be used to overwrite an existing image, creating them if they did not already exist, and not overwriting any field that is not provided.

## Path parameters

- `image_id` string, required

## Request body

- Image — Existing Image metadata model
  - `id` string, required — Image metadata unique identifier
  - `collection_id` string, required — Collection unique identifier corresponding to this image
  - `state` 'created' | 'uploaded' | 'importing' | 'imported' | 'published' | 'completed' | 'deleted' | 'failed_import' | 'failed_publish', required — The state of the image
  - `error` string — Any error information, if there was an error with this image
  - `filename` string — Image's file name. According to SEO recommendations, the name should not be longer than 5 words. And it should not include extension because multiple extensions for the same image might be available as download variants.
  - `license` object — License that defines the third party permissions for this image
    - `title` string — Title of the license
    - `href` string — Link to the license content
  - `links` ImageLinks
    - `self` string
    - `downloads` string
  - `upload` ImageUpload — Original file upload in the upload bucket
    - `path` string — S3 object key (without bucket name) where the originally uploaded image is stored
  - `type` string, required — Type of image, which might define a set of possible formats and variants or resolutions.

## Response `200`

A json with the requested image metadata

- Image — Existing Image metadata model
  - `id` string, required — Image metadata unique identifier
  - `collection_id` string, required — Collection unique identifier corresponding to this image
  - `state` 'created' | 'uploaded' | 'importing' | 'imported' | 'published' | 'completed' | 'deleted' | 'failed_import' | 'failed_publish', required — The state of the image
  - `error` string — Any error information, if there was an error with this image
  - `filename` string — Image's file name. According to SEO recommendations, the name should not be longer than 5 words. And it should not include extension because multiple extensions for the same image might be available as download variants.
  - `license` object — License that defines the third party permissions for this image
    - `title` string — Title of the license
    - `href` string — Link to the license content
  - `links` ImageLinks
    - `self` string
    - `downloads` string
  - `upload` ImageUpload — Original file upload in the upload bucket
    - `path` string — S3 object key (without bucket name) where the originally uploaded image is stored
  - `type` string, required — Type of image, which might define a set of possible formats and variants or resolutions.

## Other responses

- `400` — Invalid request, reasons can be one of the following: * image id in body, if provided, did not match the path parameter * malformed body * provided image had an invalid parameter
- `401` — User or service is not authenticated
- `403` — Unauthorised to update image or cannot be updated because the state transition is not allowed
- `404` — Requested item cannot be found
- `500` — Failed to process the request due to an internal error

---

[API](https://skmtc.net/office-of-national-statistics/apis/image-api.md) · [All operations](https://skmtc.net/office-of-national-statistics/apis/image-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/office-of-national-statistics/image-api/revisions/0d1060eb31c2/schema)