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

/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

Name Type Required Notes

version string current mediaLibraryEntry version. When set on update the version is checked.

patches

array

An 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

/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

Parameters

Name	Type	Notes
ids	string	Comma separated list of media library entry ids
externalId	string	External id of the media library entry
systemName	string	System name of the media library entry

Response

200

/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

/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

Name	Type	Required	Notes
:mediaId	string	x
?limit	integer		A limit for how much published documents to retrieve. Defaults to 100. Max. 100.
?offset	integer		An offset into the query. Useful when getting more than 100 results (pagination).

Response

200

[
  {
    "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

Name	Type	Required	Notes
:mediaId	string	x
?limit	integer		A limit for how much published documents to retrieve. Defaults to 100. Max. 100.
?offset	integer		An offset into the query. Useful when getting more than 100 results (pagination).

Response

200

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