---
title: Videos


---


## Import Videos


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

The video import does both create and update videos. 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 videos). The video import in Livingdocs is asynchronous. You post a batch of videos that you want to import and get back an id with which you can query later to get your result.

**Use Cases**

- [Initial import from a legacy system](/guides/setup/import-legacy-system-documents/llms.txt)

**History**

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

| release-2020-12 | Initial support. |

**Curl Example**

```bash
ACCESS_TOKEN=ey1234
curl -k -X POST "https://server.livingdocs.io/api/2026-05/import/videos" \
  -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/video-import",
    "videos": [
      {
        "url": "https://www.learningcontainer.com/wp-content/uploads/2020/05/sample-mp4-file.mp4",
        "id": "123abc",
        "fileName": "sample",
        "metadata": {
          "title": "sample video"
          "credit": "LC"
        }
      }
    ]
  }
  EOF
```


**Endpoint**

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


**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. |
| videos | array | x | An array of videos to import. Each entry is an object with the following keys, all of which are required:<br>- **url:** a URL to a video file, must reference a video file with mimetype `video/*`.<br>- **id:** a unique id (stored as externalId in Livingdocs) that identifies the video on your end, must be unique within your project<br>- **fileName:** the title that the video should get in livingdocs<br>- **metadata:** An object of metadata according to your project config |

**Example Request**

```js
{
  "systemName": "identifier-for-your-system",
  "webhook": "https://my-domain.com/webhooks/video-import",
  "context": {
    "myIdentifier": "some-identifier-sent-to-the-webhook"
  },
  "videos": [
    {
      "url": "https://www.learningcontainer.com/wp-content/uploads/2020/05/sample-mp4-file.mp4",
      "id": "123abc",
      "fileName": "foo",
      "metadata": {
        "title": "sample video",
        "credit": "LC"
      }
    }
  ]
}
```


**Response**

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

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




## Check Import Status for Videos


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

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

**Curl Example**

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


**Endpoint**

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


**Parameters**

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

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

**Response**

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

```json
{
  "finished": true,
  "state": "success",
  "id": "25bzj8j",
  "videos": [
    {
      "state": "success",
      "systemName": "identifier-for-your-system",
      "externalId": "external-unique-id-123",
      "video": {
        "mediaId": "jjiwhsf23kdk",
        "originalUrl": "https://livingdocs-videos.imgix.net/2019/11/21/a209790e-1549-46d9-b3c7-cefe28c7ea99.mp4",
        "mimeType": "video/mp4"
      }
    },
    {
      "state": "skipped",
      "reason": "already exists",
      "systemName": "identifier-for-your-system",
      "externalId": "external-unique-id-234",
      "video": {
        "mediaId": "jjiwhsf23wer",
        "originalUrl": "https://livingdocs-videos.imgix.net/2019/11/21/a209790e-1549-46d9-b3c7-cefe28c7ea99.mp4",
        "mimeType": "video/mp4"
      }
    },
    {
      "state": "failed",
      "reason": "Could not upload video",
      "systemName": "identifier-for-your-system",
      "externalId": "external-unique-id-345"
    }
  ]
}
```


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

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


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

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