---
title: Files


---


## Import Files


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

The file import does both create and update files. The import remembers the `externalId` / `systemName` pair and if an import matches an existing pair, it will update (Hint: consider how to rebuild the externalId when you want to update files). The file import in Livingdocs is asynchronous. You post a batch of files that you want to import and get back an id with which you can query later to get your result.

#### Related

- [Document Import API](/reference/public-api/imports/documents/llms.txt)
- [Import Media Library Entries](/reference/public-api/imports/media-library-entries/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 files and then imports documents referencing the files.

**History**

| Version | Change |
| ------- | ------ |

| release-2024-05 | Initial support. |

**Curl Example**

```bash
ACCESS_TOKEN=ey1234
curl -k -X POST "https://server.livingdocs.io/api/2026-05/import/files" \
  -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/file-import",
    "files": [
      {
        "url": "https://example.com/documents/annual-report-2023.pdf",
        "id": "file-123abc",
        "fileName": "Annual Report 2023",
        "metadata": {
          "title": "Annual Report 2023",
          "description": "Financial report for fiscal year 2023"
        }
      }
    ]
  }
  EOF
```


**Endpoint**

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


**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. |
| files | array | x | An array of files to import. Each entry is an object with the following keys, all of which are required:<br>- **url:** a URL to a file<br>- **id:** a unique id (stored as externalId in Livingdocs) that identifies the file on your end, must be unique within your project<br>- **fileName:** the title that the file should get in livingdocs<br>- **metadata:** An object of metadata according to your project config<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/file-import",
  "context": {
    "myIdentifier": "some-identifier-sent-to-the-webhook"
  },
  "files": [
    {
      "url": "https://example.com/documents/annual-report-2023.pdf",
      "id": "file-123abc",
      "fileName": "Annual Report 2023",
      "metadata": {
        "title": "Annual Report 2023",
        "description": "Financial report for fiscal year 2023"
      }
    }
  ]
}
```


**Response**

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

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




## Check Import Status for Files


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

You can use this endpoint to check for the status and/or result of a file import.

**Curl Example**

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


**Endpoint**

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


**Parameters**

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

| ?id | string | x | The id that Livingdocs provided you for your prior call to `/api/:apiVersion/import/files` |

**Response**

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

```json
{
  "finished": true,
  "state": "success",
  "id": "25bzj8j",
  "files": [
    {
      "state": "success",
      "mediaId": "jjiwhsf23kdk",
      "systemName": "identifier-for-your-system",
      "externalId": "external-unique-id-123"
    },
    {
      "state": "skipped",
      "reason": "already exists",
      "systemName": "identifier-for-your-system",
      "mediaId": "jjiwhsf23kdg",
      "externalId": "external-unique-id-234"
    },
    {
      "state": "failed",
      "reason": "Could not upload file",
      "systemName": "identifier-for-your-system",
      "externalId": "external-unique-id-345"
    }
  ]
}
```


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

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


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

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