---
title: Images


---


## Import Images


**Required scope:** `public-api:write`

The image import creates image entries in the Media Library and upload the image asset to the configured blob storage. The image import in Livingdocs is asynchronous. You post a batch of images that you want to import and get back a jobId that you can use to retrieve the import job state.

You can patch existing media library entries with the [patch endpoint](/reference/public-api/media-library/llms.txt).

**Use Cases**

- [Initial import from a legacy system](/guides/setup/import-legacy-system-documents/llms.txt) - When doing an initial import one usually first imports all images and then imports documents referencing the images.

**Curl Example**

```bash
ACCESS_TOKEN=ey1234
curl -k -X POST "https://server.livingdocs.io/api/2026-05/import/images" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  --data-binary @- << EOF
  {
    "systemName": "identifier-for-your-system",
    "webhook": "https://my-domain.com/webhooks/image-import",
    "images": [
      {
        "url": "https://placekitten.com/800/600",
        "id": "123abc",
        "fileName": "cat",
        "metadata": {
          "caption": "foo"
        }
      }
    ]
  }
  EOF
```


**Endpoint**

```http
POST /api/2026-05/import/images
```


**Parameters**

| Name | Type | Required | Notes |
| ---- | ---- | :------: | ----- |

| systemName | string | x | Identifier for the system you are importing from, e.g. an archive |
| webhook | uri |  | Endpoint at the importing system that gets notified by POST when import job is done. Notification contains the id of the import job, the state and an overview. |
| context | object |  | An object that is passed as context in the body of the request to the webhook. Limited to 8192 Bytes. |
| images | array | x | An array of images to import. Each entry is an object with the following keys, all of which are required:<br>- **url:** a URL to an image file, no data urls allowed, allowed types: png, jpg, gif, svg<br><br>- **id:** a unique id (stored as externalId in Livingdocs) that identifies the image on your end, must be unique within your project<br><br>- **fileName:** the title that the image should get in livingdocs<br><br>- **metadata:** An object of metadata according to your project config<br><br>- **mediaType:** The handle of one of the mediaTypes from your project configuration |

**Example Request**

```js
{
  "systemName": "identifier-for-your-system",
  "webhook": "https://my-domain.com/webhooks/image-import",
  "context": {
    "myIdentifier": "some-identifier-sent-to-the-webhook"
  },
  "images": [
    {
      "url": "https://placekitten.com/800/600",
      "id": "123abc",
      "fileName": "cat",
      "metadata": {
        "caption": "foo"
      }
    }
  ]
}
```


**Response**

_200 OK_ — `/api/2026-05/import/images`

```json
{
  "id": "25bzj8j"
}
```




## Check Import Status for Images


**Required scope:** `public-api:write`

API endpoints for importing and checking status of image imports.

**Curl Example**

```bash
ACCESS_TOKEN=ey1234
curl -k -X GET "https://server.livingdocs.io/api/2026-05/import/images/status" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```


**Endpoint**

```http
GET /api/2026-05/import/images/status
```


**Parameters**

| Name | Type | Required | Notes |
| ---- | ---- | :------: | ----- |

| id | string | x | The id that Livingdocs provided you for your prior call to '/import/images' |

**Response**

_200 OK_ — `/api/2026-05/import/images/status?id=25bzj8j`

```json
{
  "finished": true,
  "state": "success",
  "id": "25bzj8j",
  "images": [
    {
      "state": "success",
      "externalId": "external-unique-id-123",
      "systemName": "identifier-for-your-system",
      "image": {
        "mediaId": "jjiwhsf23kdk",
        "originalUrl": "https://livingdocs-images.imgix.net/2019/11/21/a209790e-1549-46d9-b3c7-cefe28c7ea99.jpeg",
        "url": "https://livingdocs-images.imgix.net/2019/11/21/a209790e-1549-46d9-b3c7-cefe28c7ea99.jpeg?auto=format",
        "width": 2062,
        "height": 1547,
        "mimeType": "image/jpeg",
        "imageService": "imgix"
      }
    },
    {
      "state": "skipped",
      "reason": "already exists",
      "externalId": "external-unique-id-234",
      "systemName": "identifier-for-your-system",
      "image": {
        "mediaId": "jjiwhsf23wer",
        "originalUrl": "https://livingdocs-images.imgix.net/2019/11/21/a209790e-1549-46d9-b3c7-cefe28c7ea99.jpeg?auto=format",
        "url": "https://livingdocs-images.imgix.net/2019/11/21/a209790e-1549-46d9-b3c7-cefe28c7ea99.jpeg?auto=format",
        "width": 2062,
        "height": 1547,
        "mimeType": "image/jpeg",
        "imageService": "imgix"
      }
    },
    {
      "state": "failed",
      "reason": "Could not upload image",
      "externalId": "external-unique-id-345",
      "systemName": "identifier-for-your-system"
    }
  ]
}
```


_200 OK_ — `/api/2026-05/import/images/status?id=243kdc`

```json
{
  "finished": false,
  "state": "started",
  "id": "243kdc",
  "startedAt": "2020-01-01 13:45:12"
}
```


_200 OK_ — `/api/2026-05/import/images/status?id=098shjhv9`

```json
{
  "finished": true,
  "state": "failed",
  "id": "098shjhv9"
}
```