---
title: "Create a new image metadata entry"
method: POST
path: "/images"
tags: ["image"]
---

# Create a new image metadata entry

`POST /images`

## Request

- Base URL: `/v1` (relative, and the document’s source URL is not known)
- URL: `/v1/images`
- Auth: one of:
  - API key in header `X-Florence-Token`
  - API key in header `Authorization`

Creates a new image metadata entry corresponding to the provided body in this request. A new ID will be generated for the image, and it will be set to `created` state.

## Request body

- NewImage: New Image metadata model, used to create new images. The image ID will be created by image API, and the state will be set to 'created' at creation time.
  - `state` 'created', required: The state of the image
  - `collection_id` string, required: Collection unique identifier corresponding to 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
  - `type` string, required: Type of image, which might define a set of possible formats and variants or resolutions that will be generated by the image importer.

## Response `201`

The image metadata was correctly created and a json object containing the new image information is returned. The new image will be in 'created' state and its id will be newly generated.

- 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: * collection id was incorrect * malformed body * provided image had an invalid parameter
- `401`: User or service is not authenticated
- `403`: Unauthorised to create images metadata
- `404`: Requested item cannot be found
- `500`: Failed to process the request due to an internal error

---

[API](https://skmtc.dev/office-of-national-statistics/apis/image-api.md) - [All operations](https://skmtc.dev/office-of-national-statistics/apis/image-api/llms.txt) - [OpenAPI document](https://skmtc.dev/office-of-national-statistics/apis/image-api/revisions/0d1060eb31c2?raw)