Media Library Entry

A media library entry returned by the Media Library endpoints has this top-level shape:

{
  "id": "",
  "version": 1,
  "mediaType": "",
  "asset": {},
  "metadata": {},
  "translations": [],
  "createdAt": "",
  "updatedAt": ""
}

Unlike documents, media library entries do not have a publish mechanism — all changes take effect immediately.

Top-level Fields

Property	Type	Description
`id`	`string`	Unique identifier for the media library entry.
`version`	`integer`	Version counter. Increments with each update. Used for optimistic concurrency control.
`mediaType`	`string`	The media type handle as configured in the project configs `mediaTypes`.
`asset`	`object`	The binary asset and its technical metadata. See Asset.
`metadata`	`object`	Project-configurable metadata. See Metadata.
`translations`	`array`	Locale-specific overrides for metadata and asset. See Translations.
`createdAt`	`string (ISO 8601)`	Timestamp when the entry was created.
`updatedAt`	`string (ISO 8601)`	Timestamp of the last update.

The asset object describes the uploaded file and its technical properties. Not all fields are present for every media type — for example width and height apply to images and videos, while duration applies to video files.

Property	Type	Description
`url`	`string`	Public URL of the asset.
`mimeType`	`string`	MIME type of the file (e.g. `image/jpeg`, `video/mp4`).
`width`	`integer`	Width in pixels (images and videos).
`height`	`integer`	Height in pixels (images and videos).
`size`	`integer`	File size in bytes.
`duration`	`number`	Duration in seconds (video files).
`filename`	`string`	Original filename at upload time.
`key`	`string`	Storage key used internally by Livingdocs.
`storage`	`string`	Deprecated. Storage backend identifier. Will be removed in a future version.

Metadata

Metadata fields are project-configurable. The shape of the metadata object depends on the metadata plugins configured for the media type in your project.

A common setup might include fields like title, description, credit, and source:

{
  "metadata": {
    "title": "Geneva Summit 2024",
    "description": "Aerial view of the conference center.",
    "credit": "Reuters",
    "source": "https://example.com/photos/12345"
  }
}

Translations

The translations array provides locale-specific overrides for metadata and optionally the asset itself. Each entry represents one locale.

Property	Type	Description
`locale`*	`string`	Locale identifier (e.g. `de`, `fr`, `en-US`). Must match the pattern `^[a-z][a-zA-Z0-9\-]+$`.
`metadata`*	`object`	Locale-specific metadata. Same structure as the top-level `metadata` object, with values overriding the defaults for this locale.
`asset`	`object`	Locale-specific asset override. Same structure as the top-level `asset` object. Use this when different locales need entirely different files (e.g. a localised infographic).

Complete Example

{
  "id": "a8f3k2j1",
  "version": 3,
  "mediaType": "image",
  "asset": {
    "url": "https://storage.example.com/images/summit-2024.jpg",
    "mimeType": "image/jpeg",
    "width": 2400,
    "height": 1600,
    "size": 845000,
    "filename": "summit-2024.jpg",
    "key": "images/2024/03/summit-2024.jpg"
  },
  "metadata": {
    "title": "Geneva Summit 2024",
    "description": "Aerial view of the conference center.",
    "credit": "Reuters",
    "source": "https://example.com/photos/12345"
  },
  "translations": [
    {
      "locale": "de",
      "metadata": {
        "title": "Genfer Gipfel 2024",
        "description": "Luftaufnahme des Konferenzzentrums."
      }
    },
    {
      "locale": "fr",
      "metadata": {
        "title": "Sommet de Gen\u00e8ve 2024",
        "description": "Vue a\u00e9rienne du centre de conf\u00e9rence."
      }
    }
  ],
  "createdAt": "2024-03-15T10:30:00.000Z",
  "updatedAt": "2024-03-18T14:22:10.000Z"
}