Media Library

Get a Single Media Library Entry

Required scope: public-api:read

Description

Fetch a Media Library Entries by its id.

Endpoint

GET api/v1/mediaLibrary/:id

Response

200
OK
api/v1/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

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/v1/mediaLibrary/:id" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoint

PATCH api/v1/mediaLibrary/:id

Parameters

NameTypeRequiredNotes
versionstringcurrent mediaLibraryEntry version. When set on update the version is checked.
patchesarrayxan array of patches to execute. Each entry is an object with the following keys:

operation setMetadataProperty, replaceAsset, revokeAsset, archive or removeAsset (Added in: release-2024-01)
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)

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

Get Media Library Entries

Required scope: public-api:read

Description

Fetch multiple Media Library Entries by their ids or externalIds

Endpoint

GET api/v1/mediaLibrary?ids=

GET api/v1/mediaLibrary?externalId=&systemName=

Response

200
OK
api/v1/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/v1/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

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/v1/mediaLibrary/:mediaId/incomingDocumentReferences" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoint

GET api/v1/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

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/v1/mediaLibrary/:mediaId/incomingMediaReferences" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoint

GET api/v1/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"
      }
    ]
  }
]