Media Library

Get a Single Media Library Entry

History
VersionChange
release-2020-10Initial support.

Required scope: public-api:read

Description

Fetch a Media Library Entries by its id.

Endpoint

GET /api/2026-03/mediaLibrary/{id}

Response

200
OK
/api/2026-03/mediaLibrary/{id}
{
  "id": "asze63i9",
  "version": 1,
  "mediaType": "image",
  "asset": {
    "url": "https://livingdocs.io/img.jpg",
    "mimeType": "image/jpeg",
    "width": 1600,
    "height": 900,
    "size": 21000
  },
  "metadata": {
    "title": "An Image"
  },
  "createdAt": "2020-12-27T09:19:00.928Z",
  "updatedAt": "2020-12-27T09:19:00.928Z"
}

Patch a Media Library Entry

History
VersionChange
release-2026-03Added preserveUpdatedAt parameter. When set to true, the entry’s updated_at timestamp is not modified. This is useful for imports and migrations where the original timestamps should be preserved.
release-2026-01Added unrevokeAsset operation.
Added the note property to be used with the revokeAsset operation.
release-2024-01Added removeAsset operation.
release-2022-03Added replaceAsset operation.
release-2020-12Initial support.

Required scope: public-api:write

Description

Patch a Media Library Entry by its id.

Use Cases

  • Enhancing MediaLibraryEntries. For example, update the metadata after transcoding a video or analyzing the media with an external service.
  • When having a separate DAM - update Livingdocs Media Library Entry
Curl Example
ACCESS_TOKEN=ey1234
curl -k -X PATCH "https://server.livingdocs.io/api/2026-03/mediaLibrary/{id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoint

PATCH /api/2026-03/mediaLibrary/{id}

Parameters

NameTypeRequiredNotes
versionstringcurrent mediaLibraryEntry version. When set on update the version is checked.
preserveUpdatedAtboolean

When set to true, the entry’s updated_at timestamp is not modified by the patch operation. By default (false), updated_at is set to the current time.

This is useful for imports and migrations where the original timestamps should be preserved to maintain correct sort order.

patchesarrayx

An array of patches to execute. Each entry is an object with the following keys:

  • operation setMetadataProperty, replaceAsset, revokeAsset, unrevokeAsset (Added in: release-2026-01), archive or removeAsset
  • propertyName string of the propertyName (only for setMetadataProperty)
  • value string or object for the new value. If set to null or value is not set it will remove the property for setMetadataProperty. required for replaceAsset operation.
  • locale string of the asset to be removed (only in multilingual setups for removeAsset)
  • note optional string with a maximum length of 200 characters. Only supported by the revokeAsset operation. (Added in: release-2026-01)

Example Request

{
  "version": "1",
  // When true, the entry's updated_at timestamp is preserved
  "preserveUpdatedAt": true,
  "patches": [
    {
      // update a single metadata property
      "operation": "setMetadataProperty",
      "propertyName": "title",
      "value": "updated title"
    },
    {
      // replace the asset
      "operation": "replaceAsset",
      "value": {
        // the file with this key should exist in the configured storage
        key: '2021/11/23/my-new-file.png',
        url: 'https://example.com/my-new-file.png',
        size: 10000,
        width: 1000,
        height: 800,
        filename: 'my-new-file.png',
        mimeType: 'image/png'
      }
    },
    {
      // revoke the asset
      "operation": "revokeAsset",
      "note": "Case #1"
    },
    {
      // unrevoke the asset
      "operation": "unrevokeAsset"
    },
    {
      // archives a Media Library Entry
      "operation": "archive"
    },
    {
      // removes a translated asset (the default locale asset cannot be removed)
      "operation": "removeAsset",
      "locale": "en"
    }
  ]
}

Response

200
OK
/api/2026-03/mediaLibrary/{id}
{
  "status": 200
}
400
Bad Request
/api/2026-03/mediaLibrary/{id}
{
  "status": 400,
  "error": "Bad Request",
  "error_details": {
    "patches.0.operation": "No enum match for: \"notExistingOperation\""
  }
}
404
Not Found
/api/2026-03/mediaLibrary/{id}
{
  "status": 404,
  "error": "Not Found",
  "error_details": {
    "name": "NotFound",
    "message": "MediaLibrary Entry does not exist (id: 'yLBGtTjWN4ba')"
  }
}
409
Conflict
/api/2026-03/mediaLibrary/{id}
{
  "status": 409,
  "error": "Conflict",
  "error_details": {
    "name": "Conflict",
    "message": "Version: Expected 36 to be equal to 1"
  }
}

Patch a Media Library Entry

This endpoint has changes in version 2026-03.
History
VersionChange
release-2026-01Added unrevokeAsset operation.
Added the note property to be used with the revokeAsset operation.
release-2024-01Added removeAsset operation.
release-2022-03Added replaceAsset operation.
release-2020-12Initial support.

Required scope: public-api:write

Description

Patch a Media Library Entry by its id.

Use Cases

  • Enhancing MediaLibraryEntries. For example, update the metadata after transcoding a video or analyzing the media with an external service.
  • When having a separate DAM - update Livingdocs Media Library Entry
Curl Example
ACCESS_TOKEN=ey1234
curl -k -X PATCH "https://server.livingdocs.io/api/2026-01/mediaLibrary/{id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoint

PATCH /api/2026-01/mediaLibrary/{id}

Parameters

NameTypeRequiredNotes
versionstringcurrent mediaLibraryEntry version. When set on update the version is checked.
patchesarrayx

An array of patches to execute. Each entry is an object with the following keys:

  • operation setMetadataProperty, replaceAsset, revokeAsset, unrevokeAsset (Added in: release-2026-01), archive or removeAsset
  • propertyName string of the propertyName (only for setMetadataProperty)
  • value string or object for the new value. If set to null or value is not set it will remove the property for setMetadataProperty. required for replaceAsset operation.
  • locale string of the asset to be removed (only in multilingual setups for removeAsset)
  • note optional string with a maximum length of 200 characters. Only supported by the revokeAsset operation. (Added in: release-2026-01)

Example Request

{
  "version": "1",
  "patches": [
    {
      // update a single metadata property
      "operation": "setMetadataProperty",
      "propertyName": "title",
      "value": "updated title"
    },
    {
      // replace the asset
      "operation": "replaceAsset",
      "value": {
        // the file with this key should exist in the configured storage
        key: '2021/11/23/my-new-file.png',
        url: 'https://example.com/my-new-file.png',
        size: 10000,
        width: 1000,
        height: 800,
        filename: 'my-new-file.png',
        mimeType: 'image/png'
      }
    },
    {
      // revoke the asset
      "operation": "revokeAsset",
      "note": "Case #1"
    },
    {
      // unrevoke the asset
      "operation": "unrevokeAsset"
    },
    {
      // archives a Media Library Entry
      "operation": "archive"
    },
    {
      // removes a translated asset (the default locale asset cannot be removed)
      "operation": "removeAsset",
      "locale": "en"
    }
  ]
}

Response

200
OK
/api/2026-01/mediaLibrary/{id}
{
  "status": 200
}
400
Bad Request
/api/2026-01/mediaLibrary/{id}
{
  "status": 400,
  "error": "Bad Request",
  "error_details": {
    "patches.0.operation": "No enum match for: \"notExistingOperation\""
  }
}
404
Not Found
/api/2026-01/mediaLibrary/{id}
{
  "status": 404,
  "error": "Not Found",
  "error_details": {
    "name": "NotFound",
    "message": "MediaLibrary Entry does not exist (id: 'yLBGtTjWN4ba')"
  }
}
409
Conflict
/api/2026-01/mediaLibrary/{id}
{
  "status": 409,
  "error": "Conflict",
  "error_details": {
    "name": "Conflict",
    "message": "Version: Expected 36 to be equal to 1"
  }
}

Get Media Library Entries

History
VersionChange
release-2026-01Responds with an object containing a results array.
release-2020-10Initial support.

Required scope: public-api:read

Description

Fetch multiple Media Library Entries by their ids or externalIds

Endpoint

GET /api/2026-03/mediaLibrary

Parameters

NameTypeRequiredNotes
idsstringComma separated list of media library entry ids
externalIdstringExternal id of the media library entry
systemNamestringSystem name of the media library entry

Response

200
OK
/api/2026-03/mediaLibrary?ids=asze63i9,2er11b3i
{
  "results": [
    {
      "id": "asze63i9",
      "version": 1,
      "mediaType": "image",
      "asset": {
        "url": "https://livingdocs.io/img.jpg",
        "mimeType": "image/jpeg",
        "width": 1600,
        "height": 900,
        "size": 21000
      },
      "metadata": {
        "title": "An Image"
      },
      "createdAt": "2020-12-27T09:19:00.928Z",
      "updatedAt": "2020-12-27T09:19:00.928Z"
    },
    {
      "id": "2er11b3i",
      "version": 1,
      "mediaType": "image",
      "asset": {
        "url": "https://livingdocs.io/img2.jpg",
        "mimeType": "image/jpeg",
        "width": 1600,
        "height": 900,
        "size": 21000
      },
      "metadata": {
        "title": "An Other Image"
      },
      "createdAt": "2020-12-27T09:19:00.928Z",
      "updatedAt": "2020-12-27T09:19:00.928Z"
    }
  ]
}
200
OK
/api/2026-03/mediaLibrary?externalId=ex-1&systemName=externalSystem
{
  "results": [
    {
      "id": "a77ei8nm",
      "version": 1,
      "systemName": "externalSystem",
      "externalId": "ex-1",
      "mediaType": "image",
      "asset": {
        "url": "https://livingdocs.io/img.jpg",
        "mimeType": "image/jpeg",
        "width": 1600,
        "height": 900,
        "size": 21000
      },
      "metadata": {
        "title": "An Image"
      },
      "createdAt": "2020-12-27T09:19:00.928Z",
      "updatedAt": "2020-12-27T09:19:00.928Z"
    }
  ]
}

Get Media Library Entries

This endpoint has changes in version 2026-01.
History
VersionChange
release-2020-10Initial support.

Required scope: public-api:read

Description

Fetch multiple Media Library Entries by their ids or externalIds

Endpoint

GET /api/2025-11/mediaLibrary

Parameters

NameTypeRequiredNotes
idsstringComma separated list of media library entry ids
externalIdstringExternal id of the media library entry
systemNamestringSystem name of the media library entry

Response

200
OK
/api/2025-11/mediaLibrary?ids=asze63i9,2er11b3i
{
  "mediaLibraryEntries": [
    {
      "id": "asze63i9",
      "version": 1,
      "mediaType": "image",
      "asset": {
        "url": "https://livingdocs.io/img.jpg",
        "mimeType": "image/jpeg",
        "width": 1600,
        "height": 900,
        "size": 21000
      },
      "metadata": {
        "title": "An Image"
      },
      "createdAt": "2020-12-27T09:19:00.928Z",
      "updatedAt": "2020-12-27T09:19:00.928Z"
    },
    {
      "id": "2er11b3i",
      "version": 1,
      "mediaType": "image",
      "asset": {
        "url": "https://livingdocs.io/img2.jpg",
        "mimeType": "image/jpeg",
        "width": 1600,
        "height": 900,
        "size": 21000
      },
      "metadata": {
        "title": "An Other Image"
      },
      "createdAt": "2020-12-27T09:19:00.928Z",
      "updatedAt": "2020-12-27T09:19:00.928Z"
    }
  ]
}
200
OK
/api/2025-11/mediaLibrary?externalId=ex-1&systemName=externalSystem
{
  "mediaLibraryEntries": [
    {
      "id": "a77ei8nm",
      "version": 1,
      "systemName": "externalSystem",
      "externalId": "ex-1",
      "mediaType": "image",
      "asset": {
        "url": "https://livingdocs.io/img.jpg",
        "mimeType": "image/jpeg",
        "width": 1600,
        "height": 900,
        "size": 21000
      },
      "metadata": {
        "title": "An Image"
      },
      "createdAt": "2020-12-27T09:19:00.928Z",
      "updatedAt": "2020-12-27T09:19:00.928Z"
    }
  ]
}

Get Incoming Publication References for a Media Library Entry

History
VersionChange
release-2026-01Responds with an object containing a results array, the total number of results, and a cursor for pagination.

Required scope: public-api:read

Description

This endpoint returns all publications which link to this Media Library Entry (via content or metadata)

Use Cases

  • Useful to know if the Media Library Entry is in use when revoking or archiving
Curl Example
ACCESS_TOKEN=ey1234
curl -k -X GET "https://server.livingdocs.io/api/2026-03/mediaLibrary/{mediaId}/incomingDocumentReferences" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoint

GET /api/2026-03/mediaLibrary/{mediaId}/incomingDocumentReferences

Parameters

NameTypeRequiredNotes
mediaIdstringx
?limitintegerA limit for how much published documents to retrieve. Defaults to 100. Max. 100.
?offsetintegerAn offset into the query. Useful when getting more than 100 results (pagination).
?afterstringThe cursor provided in the response can be passed back for pagination instead of using offset.

Response

200
OK
{
  "total": 5,
  "cursor": "eyJhIjpbIjE3NjUyNjIxODYuMjgyIiw2NCw2NF19",
  "results": [
    {
      "id": 2,
      "references": [
        {
          "id": "9fKagDCiN6sb",
          "type": "image",
          "location": "image-directive",
          "componentId": "doc-1ev8345oj0",
          "componentName": "image",
          "directiveName": "image"
        },
        {
          "id": "9fKagDCiN6sb",
          "type": "image",
          "location": "metadata",
          "propertyName": "teaserImage"
        }
      ]
    },
    {
      "id": 3,
      "references": [
        {
          "id": "9fKagDCiN6sb",
          "type": "image",
          "location": "image-directive",
          "componentId": "doc-1euq8lq1o0",
          "componentName": "image",
          "directiveName": "image"
        },
        {
          "id": "9fKagDCiN6sb",
          "type": "image",
          "location": "metadata",
          "propertyName": "teaserImage"
        }
      ]
    }
  ]
}

Get Incoming Publication References for a Media Library Entry

This endpoint has changes in version 2026-01.

Required scope: public-api:read

Description

This endpoint returns all publications which link to this Media Library Entry (via content or metadata)

Use Cases

  • Useful to know if the Media Library Entry is in use when revoking or archiving
Curl Example
ACCESS_TOKEN=ey1234
curl -k -X GET "https://server.livingdocs.io/api/2025-11/mediaLibrary/{mediaId}/incomingDocumentReferences" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoint

GET /api/2025-11/mediaLibrary/{mediaId}/incomingDocumentReferences

Parameters

NameTypeRequiredNotes
mediaIdstringx
?limitintegerA limit for how much published documents to retrieve. Defaults to 100. Max. 100.
?offsetintegerAn offset into the query. Useful when getting more than 100 results (pagination).

Response

200
OK
[
  {
    "id": 2,
    "references": [
      {
        "id": "9fKagDCiN6sb",
        "type": "image",
        "location": "image-directive",
        "componentId": "doc-1ev8345oj0",
        "componentName": "image",
        "directiveName": "image"
      },
      {
        "id": "9fKagDCiN6sb",
        "type": "image",
        "location": "metadata",
        "propertyName": "teaserImage"
      }
    ]
  },
  {
    "id": 3,
    "references": [
      {
        "id": "9fKagDCiN6sb",
        "type": "image",
        "location": "image-directive",
        "componentId": "doc-1euq8lq1o0",
        "componentName": "image",
        "directiveName": "image"
      },
      {
        "id": "9fKagDCiN6sb",
        "type": "image",
        "location": "metadata",
        "propertyName": "teaserImage"
      }
    ]
  }
]

Get Incoming Media References for a Media Library Entry

History
VersionChange
release-2026-01Responds with an object containing a results array, the total number of results, and a cursor for pagination.

Required scope: public-api:read

Description

This endpoint returns all Media Library Entries which link to this Media Library Entry (via metadata)
Curl Example
ACCESS_TOKEN=ey1234
curl -k -X GET "https://server.livingdocs.io/api/2026-03/mediaLibrary/{mediaId}/incomingMediaReferences" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoint

GET /api/2026-03/mediaLibrary/{mediaId}/incomingMediaReferences

Parameters

NameTypeRequiredNotes
mediaIdstringx
?limitintegerA limit for how much published documents to retrieve. Defaults to 100. Max. 100.
?offsetintegerAn offset into the query. Useful when getting more than 100 results (pagination).
?afterstringThe cursor provided in the response can be passed back for pagination instead of using offset.

Response

200
OK
{
  "total": 5,
  "cursor": "eyJhIjpbIjE3NjUyNjIxODYuMjgyIiw2NCw2NF19",
  "results": [
    {
      "id": "B1LPgANhJFpo",
      "references": [
        {
          "id": "9fKagDCiN6sb",
          "type": "image",
          "location": "metadata",
          "propertyName": "imageLink"
        }
      ]
    }
  ]
}

Get Incoming Media References for a Media Library Entry

This endpoint has changes in version 2026-01.

Required scope: public-api:read

Description

This endpoint returns all Media Library Entries which link to this Media Library Entry (via metadata)
Curl Example
ACCESS_TOKEN=ey1234
curl -k -X GET "https://server.livingdocs.io/api/2025-11/mediaLibrary/{mediaId}/incomingMediaReferences" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoint

GET /api/2025-11/mediaLibrary/{mediaId}/incomingMediaReferences

Parameters

NameTypeRequiredNotes
mediaIdstringx
?limitintegerA limit for how much published documents to retrieve. Defaults to 100. Max. 100.
?offsetintegerAn offset into the query. Useful when getting more than 100 results (pagination).

Response

200
OK
[
  {
    "id": "B1LPgANhJFpo",
    "references": [
      {
        "id": "9fKagDCiN6sb",
        "type": "image",
        "location": "metadata",
        "propertyName": "imageLink"
      }
    ]
  }
]

Serve Image

History
VersionChange
release-2025-03Initial support.

Required scope: public-api:read

Description

This endpoint delivers an image in its original dimensions, provided the asset remains valid (i.e., not revoked or marked as invalid). It is designed to serve as a reliable source for image proxies or resizing services, ensuring only authorized and valid images are accessible.
Curl Example
ACCESS_TOKEN=ey1234
curl -k -X GET "https://server.livingdocs.io/api/2026-03/mediaLibrary/serve-image/2025/03/14/c316ace8-0ded-4e41-9388-386a5759c01f.jpeg" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoint

GET /api/2026-03/mediaLibrary/serve-image/{key}

Response

200
OK
/api/2026-03/mediaLibrary/serve-image/2025/03/14/c316ace8-0ded-4e41-9388-386a5759c01f.jpeg
binary