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.
Curl Example
ACCESS_TOKEN=ey1234
curl -k -X PATCH "https://edit.livingdocs.io/proxy/api/api/v1/mediaLibrary/:id" \
  -H "Accept: 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 or archive
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.

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 (added-in release-2022-05)
      "operation": "revokeAsset"
    },
    {
      // archives a Media Library Entry (added-in release-2022-07)
      "operation": "archive"
    }
  ]
}

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

Added in: release-2022-03

Required scope: public-api:read

Curl Example
ACCESS_TOKEN=ey1234
curl -k -X GET "https://edit.livingdocs.io/proxy/api/api/v1/mediaLibrary/:mediaId/incomingDocumentReferences" \
  -H "Accept: application/json" \
  -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

Added in: release-2022-03

Required scope: public-api:read

Curl Example
ACCESS_TOKEN=ey1234
curl -k -X GET "https://edit.livingdocs.io/proxy/api/api/v1/mediaLibrary/:mediaId/incomingMediaReferences" \
  -H "Accept: application/json" \
  -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"
      }
    ]
  }
]