{ "components": { "schemas": { "CompositionApiRequestBody": { "examples": [ { "fields": [ "systemdata", "metadata", "content", "html", "includes", "design" ], "metadata": { "preload": { "myMetadataProp": true } }, "renderOptions": { "renderDirectiveInfo": true }, "resolveIncludes": true } ], "properties": { "fields": { "items": { "enum": [ "systemdata", "metadata", "content", "html", "includes", "design" ], "type": "string" }, "type": "array" }, "metadata": { "additionalProperties": false, "properties": { "preload": { "type": "object" } }, "type": "object" }, "renderOptions": { "additionalProperties": false, "properties": { "renderDirectiveInfo": { "type": "boolean" } }, "type": "object" }, "resolveIncludes": { "type": "boolean" } }, "type": "object" }, "CompositionApiResponse": { "examples": [ { "content": [ { "component": "head", "content": { "text": "some lead", "title": "a title" }, "id": "doc-1b8i1ksh10", "identifier": "timeline.head" }, { "component": "teaser", "content": { "embed-teaser": { "params": { "document": { "'$ref'": "document", "reference": { "id": 7 } } }, "service": "embed-teaser" } }, "id": "doc-2c95a77x14", "identifier": "timeline.teaser" } ], "html": "\u003cdiv\u003e...\u003c/div\u003e", "includes": [ { "componentId": "doc-2c95a77x14", "directiveName": "embed-teaser", "resolvedValue": { "content": [ { "component": "p", "content": { "text": "Some text." }, "id": "ref-7" } ] } } ], "metadata": { "description": "some lead", "title": "a title", "topic": { "'$ref'": "document", "isPreloaded": true, "reference": { "id": "5" }, "value": { "metadata": { "title": "Another title" }, "systemdata": { "channelId": 1, "contentType": "article", "design": { "name": "timeline", "version": "1.1.0" }, "documentId": 5, "documentType": "article", "firstPublicationDate": "2022-03-16T14:08:11.000Z", "projectId": 1, "publicationId": 7, "significantPublicationDate": "2022-10-26T07:25:00.000Z", "updatedAt": "2023-03-18T17:32:04.170Z", "visiblePublicationDate": "2022-10-27T06:00:00.000Z" } } } }, "systemdata": { "channelId": 1, "contentType": "article", "design": { "name": "timeline", "version": "1.1.0" }, "documentId": 1, "documentType": "article", "firstPublicationDate": "2022-03-16T14:08:11.000Z", "projectId": 1, "publicationId": 1, "significantPublicationDate": "2022-10-26T07:25:00.000Z", "updatedAt": "2023-03-18T16:32:04.170Z", "visiblePublicationDate": "2022-10-27T06:00:00.000Z" } } ], "properties": { "content": { "$ref": "#/components/schemas/Content" }, "html": { "type": "string" }, "includes": { "items": { "properties": { "componentId": { "type": "string" }, "directiveName": { "type": "string" }, "resolvedValue": { "properties": { "content": { "items": { "properties": { "component": { "type": "string" }, "content": { "type": "object" }, "id": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } }, "type": "object" }, "type": "array" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "systemdata": { "$ref": "#/components/schemas/Systemdata" } }, "type": "object" }, "Content": { "items": { "type": "object" }, "type": "array" }, "ErrorResponse": { "properties": { "error": { "type": "string" }, "error_details": { "properties": { "message": { "type": "string" } }, "type": "object" }, "status": { "type": "number" } }, "type": "object" }, "MediaLibraryEntry": { "additionalProperties": false, "properties": { "asset": { "$ref": "#/components/schemas/MediaLibraryEntryAsset" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "mediaType": { "type": "string" }, "metadata": { "type": "object" }, "translations": { "$ref": "#/components/schemas/MediaLibraryTranslations" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "type": "number" } }, "type": "object" }, "MediaLibraryEntryAsset": { "additionalProperties": false, "properties": { "duration": { "type": "number" }, "filename": { "type": "string" }, "height": { "type": "integer" }, "key": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "integer" }, "storage": { "deprecated": true, "type": "string" }, "url": { "format": "url", "type": "string" }, "width": { "type": "integer" } }, "type": "object" }, "MediaLibraryTranslations": { "items": { "additionalProperties": false, "properties": { "asset": { "$ref": "#/components/schemas/MediaLibraryEntryAsset" }, "locale": { "pattern": "^[a-z][a-zA-Z0-9\\-]+$", "type": "string" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" } }, "required": [ "locale", "metadata" ], "type": "object" }, "type": "array" }, "Metadata": { "type": "object" }, "References": { "items": { "properties": { "id": { "type": "string" }, "location": { "type": "string" }, "propertyName": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "type": "array" }, "Renditions": { "items": { "properties": { "content": { "oneOf": [ { "format": "html", "type": "string" }, { "type": "object" } ] }, "handle": { "type": "string" } }, "type": "object" }, "type": "array" }, "Systemdata": { "properties": { "channelId": { "type": "number" }, "contentType": { "type": "string" }, "design": { "properties": { "name": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "documentId": { "type": "number" }, "documentType": { "type": "string" }, "firstPublicationDate": { "format": "date-time", "type": "string" }, "layout": { "type": "string" }, "projectId": { "type": "number" }, "publicationId": { "type": "number" }, "significantPublicationDate": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "visiblePublicationDate": { "format": "date-time", "type": "string" } }, "type": "object" } }, "securitySchemes": { "bearerAuth": { "bearerFormat": "JWT", "scheme": "bearer", "type": "http" } } }, "externalDocs": { "description": "Find out more about Livingdocs", "url": "http://docs.livingdocs.io" }, "info": { "contact": { "email": "team@livingdocs.io" }, "description": "This is to quickly test the Livingdocs Public API. First create a project on your Livingdocs instance. Then create a API Client for that project. Use the token to authorize your requests. You can find out more about Livingdocs at [https://livingdocs.io](https://livingdocs.io). ", "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" }, "termsOfService": "https://livingdocs.io/terms/", "title": "Livingdocs Public API", "version": "2026-05" }, "openapi": "3.1.0", "paths": { "/api/2026-05/categories": { "get": { "description": "You need to activate the Categories / Routing Feature in the Project Config in order to query categories.", "operationId": "getAllCategories", "responses": { "200": { "content": { "application/json": { "examples": { "categories": { "value": { "results": [ { "id": "category-id-1", "label": "Category 1", "path": "/category1" }, { "id": "category-id-2", "label": "Category 2", "parent": "category-id-1", "path": "/category2" }, { "id": "category-id-3", "label": "Category 3", "path": "/category3" } ] } } }, "schema": { "properties": { "results": { "items": { "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "parent": { "type": "string" }, "path": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "badRequest": { "value": { "error": "Bad Request", "error_details": { "message": "Use of the category API requires a configurable channel. The project you requested uses a static configuration though." }, "status": 400 } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Get Categories for a Project", "tags": [ "Document Categories" ] } }, "/api/2026-05/categories/{categoryId}": { "get": { "description": "You need to activate the Categories / Routing Feature in the Project Config in order to query categories.", "operationId": "getCategoryById", "parameters": [ { "description": "Id of a specific categories as fetched from the /categories endpoint.", "in": "path", "name": "categoryId", "required": true, "schema": { "type": "string" } }, { "description": "If set to `true` will inherit (but not overwrite) metadata properties from all parents Inheritance depth is limited to 20.", "examples": { "default": { "value": false } }, "in": "query", "name": "inheritMetadata", "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": { "id": "123abc", "label": "Sport", "metadata": { "adId": "sport-ads", "analyticsCode": "sport-analytics" }, "path": "/sport" } } }, "schema": { "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "metadata": { "type": "object" }, "path": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "badRequest": { "value": { "error": "Bad Request", "error_details": { "message": "Use of the category API requires a configurable channel. The project you requested uses a static configuration though." }, "status": 400 } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" }, "500": { "content": { "application/json": { "examples": { "badRequest": { "value": { "error": "Bad Request", "error_details": { "message": "Inheritance queries can only be made up to a depth of 20." }, "status": 500 } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Get a Category with all Information", "tags": [ "Document Categories" ] } }, "/api/2026-05/composition/{documentId}": { "post": { "description": "The goal of the composition endpoint is to gather all required information to render a document in one endpoint and to work for different rendering strategies (e.g. render from JSON or use the prerendered Html). The composition Api supports rendering Html without any configuration, can preload references in metadata and can return resolved includes as JSON. It offers optimised performance for all those tasks and will replace the RenderPipeline feature. We plan to add additional functionalities like automatic design updates of documents and more to the composition Api in upcoming releases and are open for inputs what we could add.", "operationId": "composePublication", "parameters": [ { "in": "path", "name": "documentId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompositionApiRequestBody" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompositionApiResponse" } } }, "description": "OK" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Compose a publication", "tags": [ "Composition" ] } }, "/api/2026-05/design": { "get": { "description": "Get Current Design", "operationId": "getCurrentDesign", "responses": { "200": { "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Get Current Design", "tags": [ "Project" ] } }, "/api/2026-05/design/{designVersion}": { "get": { "description": "Get Specific Design", "operationId": "getDesignByVersion", "parameters": [ { "examples": { "designVersion": { "value": "3.0.0" } }, "in": "path", "name": "designVersion", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Get Specific Design", "tags": [ "Project" ] } }, "/api/2026-05/document-lists": { "get": { "description": "Get Lists", "operationId": "getAndFilterDocumentLists", "parameters": [ { "description": "Filters the result set and allows searching by list name.", "in": "query", "name": "name", "schema": { "type": "string" } }, { "description": "A limit for how much documents to resolve for the requested list. Defaults to 10. Max. 100.", "examples": { "default": { "value": 10 } }, "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 0, "type": "integer" } }, { "description": "An offset into the query. Useful when getting more than 100 results (pagination).", "examples": { "default": { "value": 0 } }, "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "categories": { "value": { "results": [ { "createdAt": "2020-11-05T10:55:51.255Z", "id": 1, "name": "List one", "updatedAt": "2020-11-05T10:55:51.255Z" }, { "createdAt": "2020-11-05T11:09:16.561Z", "id": 2, "name": "List two", "updatedAt": "2020-11-05T11:09:16.561Z" }, { "createdAt": "2020-11-05T11:09:37.213Z", "id": 3, "name": "List three", "updatedAt": "2020-11-05T11:09:37.213Z" }, { "createdAt": "2020-11-05T11:08:53.765Z", "id": 4, "name": "List four", "updatedAt": "2020-11-05T11:08:53.765Z" } ] } } }, "schema": { "properties": { "results": { "items": { "properties": { "createdAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Get Lists", "tags": [ "Document Lists" ] } }, "/api/2026-05/document-lists/{id}": { "get": { "description": "Get List by Id", "operationId": "getDocumentListById", "parameters": [ { "description": "List Id", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } }, { "description": "Pass `reverse=false` to get the list in the same order as you see it in the editor. (the default is reverse=true for backwards compatibility reasons)", "examples": { "doNotReverse": { "value": false } }, "in": "query", "name": "reverse", "schema": { "type": "boolean" } }, { "description": "Filters which (comma separated) document properties are included in the response. Defaults to `systemdata,metadata` also accepts `content` (no renditions).", "examples": { "withContent": { "value": "systemdata,metadata,content" } }, "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "A limit for how much documents to resolve for the requested list. Defaults to 100. Max. 100.", "examples": { "default": { "value": 100 } }, "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 0, "type": "integer" } }, { "description": "Provides a way to opt out of component filtering and return all content regardless of whether each component passes the conditional checks.", "examples": { "default": { "value": false } }, "in": "query", "name": "ignoreComponentConditions", "schema": { "type": "boolean" } }, { "description": "JSON stringified object which contains the component conditions you would like to apply.", "examples": { "atASpecificTime": { "value": "{\"dateTime\":\"2024-02-14T17:25:10.391Z\"}" } }, "in": "query", "name": "componentConditions", "schema": { "type": "string" } } ], "responses": { "200": { "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Get List by Id", "tags": [ "Document Lists" ] } }, "/api/2026-05/documents/latestPublications": { "get": { "description": "This endpoint is the list equivalent of the previous one. The response is an array of objects with 4 possible top-level properties: systemdata, metadata, content, references", "operationId": "getLatestPublications", "parameters": [ { "description": "Filters which (comma separated) properties are included in the response. Defaults to `systemdata,metadata,content`.", "examples": { "example": { "value": "systemdata,metadata,content,references" } }, "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "A limit for how much published documents to retrieve. Defaults to 100. Max. 100.", "examples": { "default": { "value": 100 } }, "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 0, "type": "integer" } }, { "description": "An offset into the query. Useful when getting more than 100 results (pagination)", "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "description": "Order publications in ascending order instead of the default descending order. This is useful if you want to paginate using a time based filter.", "in": "query", "name": "reverse", "schema": { "type": "boolean" } }, { "description": "Return only the document labeled as homepage in the current project.", "in": "query", "name": "homepage", "schema": { "type": "boolean" } }, { "description": "Comma separated list of content types to use as filter.", "examples": { "regularArticles": { "value": "regular" } }, "in": "query", "name": "contentTypes", "schema": { "type": "string" } }, { "description": "Comma separated list of document types to use as filter.\nCan be one of `article`, `page`, `data-record`.", "examples": { "documentTypes": { "value": "article,page,data-record" } }, "in": "query", "name": "documentTypes", "schema": { "type": "string" } }, { "description": "Filter by one or multiple document ids.\n\nExample 1: `?id=12`\n\nExample 2: `?id=100,120,123` ", "in": "query", "name": "id", "schema": { "type": "string" } }, { "description": "Filter by document id range.\n\nSupported filters: `id.gte`, `id.gt`, `id.lte`, `id.lt`.\n\nThe id range filter is useful if you want to export a lot of documents. You can do many requests in parallel against the api, where you filter by the specific ranges.\n\nThis query is much more flexible than an offset-based filter and works with millions of documents.\n\nRequest 1: ?id.gt=0\u0026id.lte=100\nRequest 2: ?id.gt=100\u0026id.lte=200\nRequest 3: ?id.gt=200\u0026id.lte=300", "in": "query", "name": "id.gte", "schema": { "type": "string" } }, { "in": "query", "name": "id.gt", "schema": { "type": "string" } }, { "in": "query", "name": "id.lte", "schema": { "type": "string" } }, { "in": "query", "name": "id.lt", "schema": { "type": "string" } }, { "description": "Filter by publish date range.\nSupported filters: `publishedAt.gte`, `publishedAt.gt`, `publishedAt.lte`, `publishedAt.lt`.\n\nExample: To retrieve all publications since a specific timestamp, use `?reverse\u0026publishedAt.gte=2021-05-01T00:00:00.000Z`", "examples": { "example": { "value": "2021-01-30T08:30:00Z" } }, "in": "query", "name": "publishedAt.gte", "schema": { "format": "date-time", "type": "string" } }, { "examples": { "example": { "value": "2021-01-30T08:30:00Z" } }, "in": "query", "name": "publishedAt.gt", "schema": { "format": "date-time", "type": "string" } }, { "examples": { "example": { "value": "2021-01-30T08:30:00Z" } }, "in": "query", "name": "publishedAt.lte", "schema": { "format": "date-time", "type": "string" } }, { "examples": { "example": { "value": "2021-01-30T08:30:00Z" } }, "in": "query", "name": "publishedAt.lt", "schema": { "format": "date-time", "type": "string" } }, { "description": "Provides a way to opt out of component filtering and return all content regardless of whether each component passes the conditional checks.", "examples": { "default": { "value": false } }, "in": "query", "name": "ignoreComponentConditions", "schema": { "type": "boolean" } }, { "description": "JSON stringified object which contains the component conditions you would like to apply.", "examples": { "atASpecificTime": { "value": "{\"dateTime\":\"2024-02-14T17:25:10.391Z\"}" } }, "in": "query", "name": "componentConditions", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": { "results": [ { "content": [ { "component": "head", "content": { "text": "some lead", "title": "a title" }, "id": "doc-1b8i1ksh10", "identifier": "timeline.head" }, { "component": "normal", "content": { "caption": "my caption" }, "id": "doc-1b8i1ksh20", "identifier": "timeline.normal", "styles": { "position": "left" } }, { "component": "p", "content": { "text": "first paragraph" }, "id": "doc-1b8i1ksh30", "identifier": "timeline.p" }, { "component": "p", "content": { "text": "second paragraph" }, "id": "doc-1b8i1me1d0", "identifier": "timeline.p" } ], "metadata": { "dependencies": {}, "description": "some lead", "title": "a title" }, "references": [ { "id": "YbzTpusGyJtF", "location": "metadata", "propertyName": "language", "type": "language-group" } ], "systemdata": { "channelId": 1, "contentType": "article", "design": { "name": "timeline", "version": "1.1.0" }, "documentId": 1, "documentType": "article", "firstPublicationDate": "2022-03-16T14:08:11.000Z", "layout": "regular", "projectId": 1, "publicationId": 1, "significantPublicationDate": "2022-10-26T07:25:00.000Z", "updatedAt": "2022-10-30T16:32:04.170Z", "visiblePublicationDate": "2022-10-27T06:00:00.000Z" } }, { "content": [ { "component": "head", "content": { "text": "some lead", "title": "a title" }, "id": "doc-1b8i1ksh10", "identifier": "timeline.head" }, { "component": "normal", "content": { "caption": "my caption" }, "id": "doc-1b8i1ksh20", "identifier": "timeline.normal", "styles": { "position": "left" } }, { "component": "p", "content": { "text": "first paragraph" }, "id": "doc-1b8i1ksh30", "identifier": "timeline.p" }, { "component": "p", "content": { "text": "second paragraph" }, "id": "doc-1b8i1me1d0", "identifier": "timeline.p" } ], "metadata": { "dependencies": {}, "description": "some other lead", "title": "another title" }, "references": [ { "id": "YbzTpusGyJtF", "location": "metadata", "propertyName": "language", "type": "language-group" } ], "systemdata": { "channelId": 1, "contentType": "article", "design": { "name": "timeline", "version": "1.1.0" }, "documentId": 2, "documentType": "article", "firstPublicationDate": "2022-03-16T14:08:11.000Z", "layout": "regular", "projectId": 1, "publicationId": 5, "significantPublicationDate": "2022-10-26T07:25:00.000Z", "updatedAt": "2022-10-30T16:32:04.170Z", "visiblePublicationDate": "2022-10-27T06:00:00.000Z" } } ] } } }, "schema": { "properties": { "results": { "items": { "properties": { "content": { "$ref": "#/components/schemas/Content" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "references": { "$ref": "#/components/schemas/References" }, "systemdata": { "$ref": "#/components/schemas/Systemdata" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Latest Publications", "tags": [ "Publications" ] } }, "/api/2026-05/documents/{documentId}/addDeliveryStatus": { "post": { "description": "This endpoint allows to provide updates for a document/publication regarding its status in an external delivery system (e.g. page build status in a static site generator). The response is a JSON object including the `reportId`.", "operationId": "addDeliveryStatusToDocument", "parameters": [ { "description": "Id of the document", "in": "path", "name": "documentId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "examples": { "addSuccessReport": { "value": { "deliveryHandle": "web", "message": "Message with \u003cstrong\u003ehtml\u003c/strong\u003e", "publicationId": 524, "reportId": "2SG2MAA9RwPn", "status": "success" } } }, "schema": { "properties": { "deliveryHandle": { "type": "string" }, "message": { "description": "String or sanitized HTML", "type": "string" }, "publicationId": { "type": "integer" }, "reportId": { "description": "If provided this will update the record, otherwise it will create a new one with a new reportId", "type": "string" }, "status": { "description": "One of: “success”, “failed”, “in-progress”", "enum": [ "success", "failed", "in-progress" ], "type": "string" } }, "required": [ "publicationId", "deliveryHandle", "status" ], "type": "object" } } } }, "responses": { "200": { "description": "successful operation" } }, "security": [ { "bearerAuth": [ "public-api:write" ] } ], "summary": "Add Delivery Status", "tags": [ "Add Delivery Status" ] } }, "/api/2026-05/documents/{documentId}/commands": { "patch": { "description": "Execute a Document Command based on its `id`. All commands run in a single transaction.", "operationId": "executeDocumentCommands", "parameters": [ { "description": "Id of the document", "in": "path", "name": "documentId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "examples": { "setTitle": { "value": { "commands": [ { "oldValue": "previous title", "operation": "setMetadataProperty", "propertyName": "title", "value": "updated title" }, { "componentId": "doc-1a2b3c4d5", "directiveName": "headline", "operation": "setEditableDirective", "value": "updated headline" }, { "operation": "publish" } ], "preconditions": [ { "type": "isPublished", "value": true } ], "version": 1 } } }, "schema": { "properties": { "commands": { "items": { "properties": { "operation": { "type": "string" } }, "type": "object" }, "type": "array" }, "preconditions": { "items": { "properties": { "type": { "type": "string" } }, "type": "object" }, "type": "array" }, "preserveUpdatedAt": { "default": false, "description": "When true, the document's updated_at timestamp is not modified. When combined with a publish command, the lastPublicationDate is also set to the preserved updated_at timestamp.", "type": "boolean" }, "version": { "type": "number" } }, "type": "object" } } } }, "responses": { "204": { "content": { "application/json": { "examples": { "success": { "value": { "status": 204 } } } } }, "description": "ok" }, "400": { "content": { "application/json": { "examples": { "invalidOperation": { "value": { "error": "Bad Request", "error_details": { "commands.0.operation": "value of tag \"operation\" must be in oneOf" }, "status": 400 } } } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "examples": { "documentNotFound": { "value": { "error": "Not Found", "error_details": { "message": "Document Not Found", "name": "NotFound" }, "status": 404 } } } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "examples": { "versionConflict": { "value": { "error": "Conflict", "error_details": { "currentVersion": 2, "expectedVersion": 1, "message": "The document you tried to update is outdated", "name": "Conflict" }, "status": 409 } } } } }, "description": "Conflict" } }, "security": [ { "bearerAuth": [ "public-api:write" ] } ], "summary": "Execute Commands on Documents. Added in release-2023-11.", "tags": [ "Document Command API" ] } }, "/api/2026-05/documents/{documentId}/incomingDocumentReferences": { "get": { "description": "Get Incoming Publication References for a Document", "operationId": "getIncomingDocumentReferencesForDocument", "parameters": [ { "in": "path", "name": "documentId", "required": true, "schema": { "type": "integer" } }, { "description": "A limit for how much published documents to retrieve. Defaults to 100. Max. 100.", "examples": { "default": { "value": 100 } }, "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "An offset into the query. Useful when getting more than 100 results (pagination).", "examples": { "default": { "value": 0 } }, "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "description": "The `cursor` provided in the response can be passed back for pagination instead of using `offset`.", "examples": { "cursor": { "value": "eyJhIjpbIjE3NjUyNjIxODYuMjgyIiw2NCw2NF19" } }, "in": "query", "name": "?after", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": { "cursor": "eyJhIjpbIjE3NjUyNjIxODYuMjgyIiw2NCw2NF19", "results": [ { "id": 4, "references": [ { "componentId": "doc-1euiflvoq0", "componentName": "teaser-include", "directiveName": "teaser", "id": "1", "location": "include-directive", "propertyName": "article", "serviceName": "editable-teaser", "type": "document" } ] }, { "id": 2, "references": [ { "componentId": "doc-1eu6i7l880", "componentName": "teaser-include", "directiveName": "teaser", "id": "1", "location": "include-directive", "propertyName": "article", "serviceName": "editable-teaser", "type": "document" } ] } ], "total": 7 } } }, "schema": { "properties": { "cursor": { "type": "string" }, "results": { "items": { "properties": { "id": { "type": "integer" }, "references": { "items": { "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "total": { "type": "integer" } }, "type": "object" } } }, "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Incoming Publication References", "tags": [ "Publications" ] } }, "/api/2026-05/documents/{documentId}/incomingMediaReferences": { "get": { "description": "Get Incoming Media References for a Document. Added in: [release-2022-03](https://docs.livingdocs.io/operations/releases/release-2022-03/release-2022-03/)", "operationId": "getIncomingMediaReferencesForDocument", "parameters": [ { "in": "path", "name": "documentId", "required": true, "schema": { "type": "integer" } }, { "description": "A limit for how much published documents to retrieve. Defaults to 100. Max. 100.", "examples": { "default": { "value": 100 } }, "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "An offset into the query. Useful when getting more than 100 results (pagination).", "examples": { "default": { "value": 0 } }, "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "description": "The `cursor` provided in the response can be passed back for pagination instead of using `offset`.", "examples": { "cursor": { "value": "eyJhIjpbIjE3NjUyNjIxODYuMjgyIiw2NCw2NF19" } }, "in": "query", "name": "?after", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": { "cursor": "eyJhIjpbIjE3NjUyNjIxODYuMjgyIiw2NCw2NF19", "results": [ { "id": "98sXCahM5PEk", "references": [ { "id": "3", "location": "metadata", "propertyName": "documentLink", "type": "document" } ] } ], "total": 2 } } }, "schema": { "properties": { "cursor": { "type": "string" }, "results": { "items": { "properties": { "id": { "type": "integer" }, "references": { "items": { "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "total": { "type": "integer" } }, "type": "object" } } }, "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Incoming Media References", "tags": [ "Publications" ] } }, "/api/2026-05/documents/{documentId}/latestDraft": { "get": { "description": "**Added in:** [release-2022-03](https://docs.livingdocs.io/operations/releases/release-2022-03/release-2022-03/)\n\n**Required scope:** `public-api:write` `public-api:drafts:read`\n\nThis endpoint returns the most recent draft version of a document. A token with permission The response is a JSON object with 5 possible top-level properties: \n- systemdata \n- metadata \n- content \n- references", "operationId": "getLatestDraftForDocument", "parameters": [ { "in": "path", "name": "documentId", "required": true, "schema": { "type": "integer" } }, { "description": "Provides a way to opt out of component filtering and return all content regardless of whether each component passes the conditional checks.", "examples": { "default": { "value": false } }, "in": "query", "name": "ignoreComponentConditions", "schema": { "type": "boolean" } }, { "description": "JSON stringified object which contains the component conditions you would like to apply.", "examples": { "atASpecificTime": { "value": "{\"dateTime\":\"2024-02-14T17:25:10.391Z\"}" } }, "in": "query", "name": "componentConditions", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": { "content": [ { "component": "article-container", "containers": { "main": [ { "component": "paragraph", "content": { "text": "First paragraph published." }, "id": "doc-1fsh4faeo3", "identifier": "living-times.paragraph" }, { "component": "paragraph", "content": { "text": "Second paragraph unpublished." }, "id": "doc-1fsh4g83l0", "identifier": "living-times.paragraph" } ] }, "id": "doc-1fsh4faeo0", "identifier": "living-times.article-container", "position": "fixed" } ], "metadata": { "language": { "groupId": "KjqXSj2P1-L0", "label": "German", "locale": "de" }, "title": "Draft (Changed)" }, "references": [ { "id": "KjqXSj2P1-L0", "location": "metadata", "propertyName": "language", "type": "language-group" } ], "systemdata": { "channelId": 1, "contentType": "regular", "design": { "name": "living-times", "version": "1.0.4" }, "documentId": 603, "documentType": "article", "firstPublicationDate": "2022-02-22T16:33:42.836Z", "projectId": 1, "updatedAt": "2022-02-22T16:33:42.836Z" } } } }, "schema": { "properties": { "content": { "$ref": "#/components/schemas/Content" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "references": { "$ref": "#/components/schemas/References" }, "systemdata": { "$ref": "#/components/schemas/Systemdata" } }, "type": "object" } } }, "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:write", "public-api:drafts:read" ] } ], "summary": "Get Latest Draft", "tags": [ "Drafts" ] } }, "/api/2026-05/documents/{documentId}/latestPublication": { "get": { "description": "Required scope: public-api:read. The response is a JSON object with 4 possible top-level properties: systemdata, references, metadata, content", "operationId": "getLatestPublicationForDocument", "parameters": [ { "in": "path", "name": "documentId", "required": true, "schema": { "type": "integer" } }, { "description": "Filters which (comma separated) properties are included in the response. Defaults to `systemdata,references,metadata,content`.", "examples": { "all": { "value": "systemdata,references,metadata,content" } }, "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Provides a way to opt out of component filtering and return all content regardless of whether each component passes the conditional checks.", "examples": { "default": { "value": false } }, "in": "query", "name": "ignoreComponentConditions", "schema": { "type": "boolean" } }, { "description": "JSON stringified object which contains the component conditions you would like to apply.", "examples": { "atASpecificTime": { "value": "{\"dateTime\":\"2024-02-14T17:25:10.391Z\"}" } }, "in": "query", "name": "componentConditions", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "examples": [ { "content": [ { "component": "head", "content": { "text": "some lead", "title": "a title" }, "id": "doc-1b8i1ksh10", "identifier": "timeline.head" }, { "component": "normal", "content": { "caption": "my caption" }, "id": "doc-1b8i1ksh20", "identifier": "timeline.normal", "styles": { "position": "left" } }, { "component": "p", "content": { "text": "first paragraph" }, "id": "doc-1b8i1ksh30", "identifier": "timeline.p" }, { "component": "p", "content": { "text": "second paragraph" }, "id": "doc-1b8i1me1d0", "identifier": "timeline.p" } ], "metadata": { "dependencies": {}, "description": "some lead", "title": "a title" }, "renditions": [ { "content": "\u003cdiv class=\"head\"\u003e\n \u003ch1\u003ea title\u003c/h1\u003e\n \u003cp class=\"lead\"\u003esome lead\u003c/p\u003e\n\u003c/div\u003e\n\u003cfigure class=\"aspect-ratio left\"\u003e\n \u003cimg class=\"doc-image-empty\" src=\"data:image/svg+xml;charset=UTF-8,…\"\u003e\n \u003cfigcaption\u003emy caption\u003c/figcaption\u003e\n\u003c/figure\u003e\n\u003cp\u003efirst paragraph\u003c/p\u003e\n\u003cp\u003esecond\u003c/p\u003e\n\u003cp\u003e and third one. :)\u003c/p\u003e", "handle": "web" }, { "content": { "content": [ { "component": "head", "content": { "text": "some lead", "title": "a title" }, "id": "doc-1b8i1ksh10", "identifier": "timeline.head" }, { "component": "normal", "content": { "caption": "my caption" }, "id": "doc-1b8i1ksh20", "identifier": "timeline.normal", "styles": { "position": "left" } }, { "component": "p", "content": { "text": "first paragraph" }, "id": "doc-1b8i1ksh30", "identifier": "timeline.p" }, { "component": "p", "content": { "text": "second paragraph" }, "id": "doc-1b8i1me1d0", "identifier": "timeline.p" } ], "design": { "name": "timeline", "version": "1.1.0" } }, "handle": "mobile" }, { "error": { "message": "Processing of Channel 'app' for document '1' failed. Detailed error message…" }, "handle": "app" } ], "systemdata": { "channelId": 1, "contentType": "regular", "design": { "name": "timeline", "version": "1.1.0" }, "documentId": 1, "documentType": "article", "firstPublicationDate": "2022-03-16T14:08:11.000Z", "layout": "regular", "projectId": 1, "publicationId": 1, "significantPublicationDate": "2022-10-26T07:25:00.000Z", "updatedAt": "2023-03-18T16:32:04.170Z", "visiblePublicationDate": "2022-10-27T06:00:00.000Z" } } ], "properties": { "content": { "$ref": "#/components/schemas/Content" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "references": { "$ref": "#/components/schemas/References" }, "systemdata": { "$ref": "#/components/schemas/Systemdata" } }, "type": "object" } } }, "description": "OK" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Latest Publication", "tags": [ "Publications" ] } }, "/api/2026-05/drafts/{documentId}/incomingDocumentReferences": { "get": { "description": "This endpoint is functionally equivalent to the incoming document references endpoint for publications. But with this draft endpoint you will receive references from unpublished documents as well as references from the current state of documents even if these latest updates to the document are not published yet.", "operationId": "getIncomingDraftReferences", "parameters": [ { "in": "path", "name": "documentId", "required": true, "schema": { "type": "integer" } }, { "description": "A limit for how much documents to retrieve. Defaults to 100. Max. 100.", "examples": { "default": { "value": 100 } }, "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "An offset into the query. Useful when getting more than 100 results (pagination).", "examples": { "default": { "value": 0 } }, "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "description": "The `cursor` provided in the response can be passed back for pagination instead of using `offset`.", "examples": { "cursor": { "value": "eyJhIjpbIjE3NjUyNjIxODYuMjgyIiw2NCw2NF19" } }, "in": "query", "name": "?after", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": { "cursor": "eyJhIjpbIjE3NjUyNjIxODYuMjgyIiw2NCw2NF19", "results": [ { "id": 4, "references": [ { "componentId": "doc-1euiflvoq0", "componentName": "teaser-include", "directiveName": "teaser", "id": "1", "location": "include-directive", "propertyName": "article", "serviceName": "editable-teaser", "type": "document" } ] }, { "id": 2, "references": [ { "componentId": "doc-1eu6i7l880", "componentName": "teaser-include", "directiveName": "teaser", "id": "1", "location": "include-directive", "propertyName": "article", "serviceName": "editable-teaser", "type": "document" } ] } ], "total": 5 } } }, "schema": { "properties": { "cursor": { "type": "string" }, "results": { "items": { "properties": { "id": { "type": "integer" }, "references": { "items": { "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "total": { "type": "integer" } }, "type": "object" } } }, "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:drafts:read" ] } ], "summary": "Get Incoming Draft References for a Document", "tags": [ "Drafts" ] } }, "/api/2026-05/health": { "get": { "description": "Check API Status", "operationId": "getApiStatus", "responses": { "200": { "description": "Status ok" } }, "summary": "Check API Status", "tags": [ "Health" ] } }, "/api/2026-05/import/documents": { "post": { "description": "The document import does both create and update documents. The import remembers the `externalId` / `systemName` pair and if an import matches an existing pair, it will update (Hint: consider how to rebuild the `externalId` when you want to update documents). The document import in Livingdocs is asynchronous. You post a batch of documents that you want to import and get back an id with which you can query later to get your result.", "operationId": "getImportDocuments", "requestBody": { "content": { "application/json": { "examples": { "example": { "value": { "context": { "myIdentifier": "some-identifier-sent-to-the-webhook" }, "documents": [ { "checksum": "xyz456", "contentType": "article", "flags": { "autoPublish": true }, "id": "123abc", "livingdoc": { "content": [ { "content": { "author": "imported author", "catchline": "imported catchline", "title": "imported title" }, "identifier": "header" } ], "design": { "name": "living-times", "version": "1.0.1" } }, "metadata": { "description": "foo" }, "publicationDate": "1999-03-18T17:27:00.107Z", "title": "test import", "translations": [ { "locale": "fr", "metadata": { "description": "foo FR" } } ] } ], "systemName": "identifier-for-your-system", "webhook": "https://my-domain.com/webhooks/document-import" } } }, "schema": { "properties": { "context": { "description": "An object that is passed as context in the body of the request to the webhook. Limited to 8192 Bytes.", "type": "object" }, "documents": { "description": "An array of documents to import. Each entry is an object.", "items": { "properties": { "checksum": { "description": "string to identify changes, e.g. an updated_at timestamp", "type": "string" }, "contentType": { "description": "the content type that the document should get in livingdocs", "type": "string" }, "flags": { "description": "(optional) define additional import logic: \n`autoPublish`: publishes imported documents immediately \n`unpublish`: unpublishes imported documents immediately (release-2022-07)\n`onlyOverwriteUntouched`: only update documents that have no manual changes in livingdocs\n`neverOverwrite`: never update documents through the import API", "type": "object" }, "id": { "description": "a unique id (stored as externalId in Livingdocs) that identifies the document on your end, must be unique within your project.", "type": "string" }, "livingdoc": { "description": "A valid livingdoc declaration (content / design), must conform to your channel-config otherwise throws a validation error / release-2022-07: if no design is set it takes the design of the Project Config.", "type": "object" }, "metadata": { "description": "An object of metadata, must conform to your channel-config otherwise throws a validation error", "type": "object" }, "publicationDate": { "description": "sets the date of a publication. `autoPublish’ flag must be set for this to have an effect.", "format": "date-time", "type": "string" }, "title": { "description": "the title that the document should get in livingdocs", "type": "string" }, "translations": { "description": "sets the date of a publication. `autoPublish` flag must be set for this to have an effect.", "items": { "type": "object" }, "type": "array" } }, "required": [ "id", "checksum", "title", "contentType", "publicationDate", "livingdoc", "metadata" ], "type": "object" }, "type": "array" }, "systemName": { "description": "Identifier for the system you are importing from, e.g. an archive", "type": "string" }, "webhook": { "description": "Endpoint at the importing system that gets notified by POST when import job is done. Notification contains the id of the import job, the state and an overview.", "format": "uri", "type": "string" } }, "required": [ "systemName", "documents" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": { "id": "25bzj8j" } } }, "schema": { "properties": { "id": { "type": "string" } }, "type": "object" } } }, "description": "ok" }, "429": { "content": { "application/json": { "examples": { "usageLimitExceeded": { "value": { "error": "Usage Limit Exceeded", "error_details": { "message": "Your plan does not allow you to upload more than 100 per day.\n You already uploaded 99 in the last 24 hours and are trying to upload 10 more.\n Please try again later." }, "status": 429 } } }, "schema": { "items": { "type": "object" }, "type": "array" } } }, "description": "Usage Limit Exceeded" } }, "security": [ { "bearerAuth": [ "public-api:write" ] } ], "summary": "Import Documents", "tags": [ "Imports" ] } }, "/api/2026-05/import/documents/status": { "get": { "description": "You can use this endpoint to check for the status and/or result of a document import.", "operationId": "getDocumentImportStatus", "parameters": [ { "in": "query", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": { "finished": true, "id": "25bzj8j", "logs": [ { "channel_id": 2, "checksum": "123abc", "document_id": 1, "external_id": "8Sv9Nu0d", "id": 1, "project_id": 3, "revision_id": 1, "state": "imported", "system_name": "integration-tests", "version": 1 }, { "external_id": "external-unique-id-345", "reason": "Invalid metadata", "state": "failed", "title": "my second document" } ], "state": "success" } } }, "schema": { "type": "object" } } }, "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:write" ] } ], "summary": "Check Import Status for Documents", "tags": [ "Imports" ] } }, "/api/2026-05/import/files": { "post": { "description": "The file import does both create and update files. The import remembers the `externalId` / `systemName` pair and if an import matches an existing pair, it will update (Hint: consider how to rebuild the `externalId` when you want to update files). The file import in Livingdocs is asynchronous. You post a batch of files that you want to import and get back an id with which you can query later to get your result.", "operationId": "importFiles", "requestBody": { "content": { "application/json": { "examples": { "import": { "value": { "context": { "myIdentifier": "some-identifier-sent-to-the-webhook" }, "files": [ { "fileName": "Annual Report 2023", "id": "file-123abc", "mediaType": "file", "metadata": { "description": "Financial report for fiscal year 2023", "title": "Annual Report 2023" }, "url": "https://example.com/documents/annual-report-2023.pdf" }, { "fileName": "Sales Data 2023", "id": "file-456def", "mediaType": "file", "metadata": { "description": "Quarterly sales figures for 2023", "title": "Sales Data 2023" }, "url": "https://example.com/spreadsheets/sales-data-2023.xlsx" } ], "systemName": "identifier-for-your-system", "webhook": "https://my-domain.com/webhooks/file-import" } } }, "schema": { "properties": { "context": { "description": "An object that is passed as context in the body of the request to the webhook. Limited to 8192 Bytes.", "type": "object" }, "files": { "description": "An array of files to import. Each entry is an object with the following keys, all of which are required:", "items": { "properties": { "fileName": { "description": "the title that the file should get in livingdocs", "type": "string" }, "id": { "description": "a unique id (stored as externalId in Livingdocs) that identifies the file on your end, must be unique within your project.", "type": "string" }, "mediaType": { "description": "the handle of one of the mediaTypes from your project configuration", "type": "string" }, "metadata": { "description": "An object of metadata according to your project config", "type": "object" }, "url": { "description": "a URL to a file", "format": "uri", "type": "string" } }, "required": [ "id", "url", "fileName", "metadata" ], "type": "object" }, "type": "array" }, "systemName": { "description": "Identifier for the system you are importing from, e.g. an archive", "type": "string" }, "webhook": { "description": "Endpoint at the importing system that gets notified by POST when import job is done. Notification contains the id of the import job, the state and an overview.", "format": "uri", "type": "string" } }, "required": [ "systemName", "files" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": { "id": "25bzj8j" } } }, "schema": { "properties": { "id": { "type": "string" } }, "type": "object" } } }, "description": "ok" }, "429": { "content": { "application/json": { "examples": { "usageLimitExceeded": { "value": { "error": "Usage Limit Exceeded", "error_details": { "message": "Your plan does not allow you to upload more than 100 per day.\n You already uploaded 99 in the last 24 hours and are trying to upload 10 more.\n Please try again later." }, "status": 429 } } }, "schema": { "items": { "type": "object" }, "type": "array" } } }, "description": "Usage Limit Exceeded" } }, "security": [ { "bearerAuth": [ "public-api:write" ] } ], "summary": "Import Files", "tags": [ "Imports" ] } }, "/api/2026-05/import/files/status": { "get": { "description": "You can use this endpoint to check for the status and/or result of a file import.", "operationId": "getFileImportStatus", "parameters": [ { "description": "The id that Livingdocs provided you for your prior call to `/import/files`", "in": "query", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "failed": { "value": { "finished": true, "id": "098shjhv9", "state": "failed" } }, "inProgress": { "value": { "finished": false, "id": "243kdc", "startedAt": "2020-01-01 13:45:12", "state": "started" } }, "success": { "value": { "files": [ { "externalId": "external-unique-id-123", "mediaId": "jjiwhsf23kdk", "state": "success", "systemName": "identifier-for-your-system" }, { "externalId": "external-unique-id-234", "mediaId": "jjiwhsf23kdg", "reason": "already exists", "state": "skipped", "systemName": "identifier-for-your-system" }, { "externalId": "external-unique-id-345", "reason": "Could not upload file", "state": "failed", "systemName": "identifier-for-your-system" } ], "finished": true, "id": "25bzj8j", "state": "success" } } }, "schema": { "type": "object" } } }, "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:write" ] } ], "summary": "Check Import Status for Files", "tags": [ "Imports" ] } }, "/api/2026-05/import/images": { "post": { "description": "The image import does both create and update images. The import remembers the `externalId` / `systemName` pair and if an import matches an existing pair, it will update (Hint: consider how to rebuild the `externalId` when you want to update images). The image import in Livingdocs is asynchronous. You post a batch of images that you want to import and get back an id with which you can query later to get your result.", "operationId": "importImage", "requestBody": { "content": { "application/json": { "examples": { "import": { "value": { "context": { "myIdentifier": "some-identifier-sent-to-the-webhook" }, "images": [ { "fileName": "cat", "id": "123abc", "mediaType": "image", "metadata": { "title": "kitten" }, "url": "https://placekitten.com/800/600" } ], "systemName": "identifier-for-your-system", "webhook": "https://my-domain.com/webhooks/image-import" } } }, "schema": { "properties": { "context": { "description": "An object that is passed as context in the body of the request to the webhook. Limited to 8192 Bytes.", "type": "object" }, "images": { "description": "An array of images to import. Each entry is an object with the following keys, all of which are required:", "items": { "properties": { "fileName": { "description": "the title that the image should get in livingdocs", "type": "string" }, "id": { "description": "a unique id (stored as externalId in Livingdocs) that identifies the document on your end, must be unique within your project.", "type": "string" }, "mediaType": { "description": "the handle of one of the mediaTypes from your project configuration", "type": "string" }, "metadata": { "description": "An object of metadata according to your project config", "type": "object" }, "url": { "description": "a URL to an image file, no data urls allowed, must be an image, allowed types: png, jpg, gif, svg", "format": "uri", "type": "string" } }, "required": [ "id", "url", "fileName", "metadata", "mediaType" ], "type": "object" }, "type": "array" }, "systemName": { "description": "Identifier for the system you are importing from, e.g. an archive", "type": "string" }, "webhook": { "description": "Endpoint at the importing system that gets notified by POST when import job is done. Notification contains the id of the import job, the state and an overview.", "format": "uri", "type": "string" } }, "required": [ "systemName", "images" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": { "id": "25bzj8j" } } }, "schema": { "properties": { "id": { "type": "string" } }, "type": "object" } } }, "description": "ok" }, "429": { "content": { "application/json": { "examples": { "usageLimitExceeded": { "value": { "error": "Usage Limit Exceeded", "error_details": { "message": "Your plan does not allow you to upload more than 100 per day.\n You already uploaded 99 in the last 24 hours and are trying to upload 10 more.\n Please try again later." }, "status": 429 } } }, "schema": { "items": { "type": "object" }, "type": "array" } } }, "description": "Usage Limit Exceeded" } }, "security": [ { "bearerAuth": [ "public-api:write" ] } ], "summary": "Import Images", "tags": [ "Imports" ] } }, "/api/2026-05/import/images/status": { "get": { "description": "You can use this endpoint to check for the status and/or result of a image import.", "operationId": "getImageImportStatus", "parameters": [ { "description": "The id that Livingdocs provided you for your prior call to `/import/images`", "in": "query", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "failed": { "value": { "finished": true, "id": "098shjhv9", "state": "failed" } }, "inProgress": { "value": { "finished": false, "id": "243kdc", "startedAt": "2020-01-01 13:45:12", "state": "started" } }, "success": { "value": { "finished": true, "id": "25bzj8j", "images": [ { "externalId": "external-unique-id-123", "image": { "height": 1547, "imageService": "imgix", "mediaId": "jjiwhsf23kdk", "mimeType": "image/jpeg", "originalUrl": "https://livingdocs-images.imgix.net/2019/11/21/a209790e-1549-46d9-b3c7-cefe28c7ea99.jpeg", "url": "https://livingdocs-images.imgix.net/2019/11/21/a209790e-1549-46d9-b3c7-cefe28c7ea99.jpeg?auto=format", "width": 2062 }, "state": "success", "systemName": "identifier-for-your-system" }, { "externalId": "external-unique-id-234", "image": { "height": 1547, "imageService": "imgix", "mediaId": "jjiwhsf23wer", "mimeType": "image/jpeg", "originalUrl": "https://livingdocs-images.imgix.net/2019/11/21/a209790e-1549-46d9-b3c7-cefe28c7ea99.jpeg", "url": "https://livingdocs-images.imgix.net/2019/11/21/a209790e-1549-46d9-b3c7-cefe28c7ea99.jpeg?auto=format", "width": 2062 }, "reason": "already exists", "state": "skipped", "systemName": "identifier-for-your-system" }, { "externalId": "external-unique-id-345", "reason": "Could not upload image", "state": "failed", "systemName": "identifier-for-your-system" } ], "state": "success" } } }, "schema": { "type": "object" } } }, "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:write" ] } ], "summary": "Check Import Status for Images", "tags": [ "Imports" ] } }, "/api/2026-05/import/mediaLibrary": { "post": { "description": "When you can upload images to the configured Media Library storage (e.g. AWS S3) yourself it is possible to create Media Library Entries through the API.\n\nThis has the advantage that the entris will be included in the response directly in contrast to the importImages endpoint where you only get a job id.\n\nYou can also provide a custom id to entries which helps with importing documents where images in the document should be referenced with the correct `mediaId` maybe even before creating the Media Library Entries themselves.", "operationId": "importMediaLibraryEntries", "requestBody": { "content": { "application/json": { "examples": { "post": { "value": { "mediaLibraryEntries": [ { "asset": { "filename": "super-mario.jpeg", "height": 427, "key": "2022/08/25/d6068c02-ca85-421d-948d-ee0e2c15f372.jpeg", "mimeType": "image/jpeg", "size": 34910, "url": "https://livingdocs-images-development.s3.amazonaws.com/2022/08/25/d6068c02-ca85-421d-948d-ee0e2c15f372.jpeg", "width": 640 }, "externalId": "6hedie82", "id": "custom-1", "mediaType": "image", "metadata": { "title": "This is Super Mario!" }, "systemName": "externalSystem", "translations": [ { "asset": { "filename": "jpg-super-mario-wall.jpg", "height": 853, "key": "2022/09/30/60984f90-c766-4546-9bc8-61f0832f9755.jpeg", "mimeType": "image/jpeg", "size": 188497, "url": "https://livingdocs-images-development.s3.amazonaws.com/2022/09/30/60984f90-c766-4546-9bc8-61f0832f9755.jpeg", "width": 640 }, "locale": "fr", "metadata": { "title": "C'est Super Mario!" } } ] }, { "asset": { "filename": "a-simple-pdf.pdf", "key": "2022/09/30/a1cb173d-e85f-498b-996e-5ce46058e9b9.pdf", "mimeType": "application/pdf", "size": 3028, "url": "https://livingdocs-files-development.s3.amazonaws.com/2022/09/30/a1cb173d-e85f-498b-996e-5ce46058e9b9.pdf" }, "externalId": "ahedie8x", "id": "custom-2", "mediaType": "file", "metadata": { "title": "A simple PDF" }, "systemName": "externalSystem", "translations": [ { "locale": "fr", "metadata": { "title": "Un simple PDF" } } ] }, { "asset": { "duration": 35.241667, "filename": "fire.mp4", "height": 720, "key": "2022/09/30/2804fc3d-098d-4f8f-b25c-c6c15583d672.mp4", "mimeType": "video/mp4", "size": 8633462, "url": "https://livingdocs-videos-development.s3.amazonaws.com/2022/09/30/2804fc3d-098d-4f8f-b25c-c6c15583d672.mp4", "width": 1280 }, "externalId": "srfhediess", "id": "custom-3", "mediaType": "video", "metadata": { "title": "This is a fire" }, "systemName": "externalSystem", "translations": [ { "locale": "fr", "metadata": { "title": "C'est un feu" } } ] } ] } } }, "schema": { "properties": { "mediaLibraryEntries": { "description": "An array of documents to import. Each entry is an object.", "items": { "discriminator": { "propertyName": "mediaType" }, "oneOf": [ { "properties": { "asset": { "properties": { "filename": { "type": "string" }, "height": { "type": "number" }, "key": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "number" }, "url": { "format": "uri", "pattern": "(http)?s?:?(\\/\\/[^\"']*\\.(?:png|jpg|jpeg|gif|png|svg|webp|mp4|mov))", "type": "string" }, "width": { "type": "number" } }, "required": [ "key", "url", "size", "width", "height", "mimeType", "filename" ], "type": "object" }, "externalId": { "description": "Must be unique in combination with systemName.", "type": "string" }, "id": { "description": "Custom id (Allowed characters: a-z, A-Z, 0-9, and -). If omitted a random id will be generated.", "pattern": "^[a-zA-Z0-9\\-]{1,32}$", "type": "string" }, "mediaType": { "enum": [ "image" ], "type": "string" }, "metadata": { "type": "object" }, "systemName": { "description": "A string identifiyng the external system where the asset is imported from. It is recommended that you always set this value and it is required if you provide an externalId.", "type": "string" }, "translations": { "$ref": "#/components/schemas/MediaLibraryTranslations" } }, "required": [ "mediaType", "asset" ], "type": "object" }, { "properties": { "asset": { "properties": { "filename": { "type": "string" }, "key": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "number" }, "url": { "format": "uri", "pattern": "(http)?s?:?(\\/\\/[^\"']*\\.*)", "type": "string" } }, "required": [ "key", "url", "size", "mimeType", "filename" ], "type": "object" }, "externalId": { "description": "Must be unique in combination with systemName.", "type": "string" }, "id": { "description": "Custom id (Allowed characters: a-z, A-Z, 0-9, and -). If omitted a random id will be generated.", "pattern": "^[a-zA-Z0-9\\-]{1,32}$", "type": "string" }, "mediaType": { "enum": [ "file" ], "type": "string" }, "metadata": { "type": "object" }, "systemName": { "description": "A string identifiyng the external system where the asset is imported from. It is recommended that you always set this value and it is required if you provide an externalId.", "type": "string" }, "translations": { "$ref": "#/components/schemas/MediaLibraryTranslations" } }, "required": [ "mediaType", "asset" ], "type": "object" }, { "properties": { "asset": { "properties": { "duration": { "type": "number" }, "filename": { "type": "string" }, "height": { "type": "number" }, "key": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "number" }, "url": { "format": "uri", "pattern": "(http)?s?:?(\\/\\/[^\"']*\\.*)", "type": "string" }, "width": { "type": "number" } }, "required": [ "key", "url", "size", "width", "height", "duration", "mimeType", "filename" ], "type": "object" }, "externalId": { "description": "Must be unique in combination with systemName.", "type": "string" }, "id": { "description": "Custom id (Allowed characters: a-z, A-Z, 0-9, and -). If omitted a random id will be generated.", "pattern": "^[a-zA-Z0-9\\-]{1,32}$", "type": "string" }, "mediaType": { "enum": [ "video" ], "type": "string" }, "metadata": { "type": "object" }, "systemName": { "description": "A string identifiyng the external system where the asset is imported from. It is recommended that you always set this value and it is required if you provide an externalId.", "type": "string" }, "translations": { "$ref": "#/components/schemas/MediaLibraryTranslations" } }, "required": [ "mediaType", "asset" ], "type": "object" } ], "properties": { "mediaType": { "type": "string" } }, "required": [ "mediaType" ], "type": "object" }, "type": "array" } }, "required": [ "mediaLibraryEntries" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": { "results": [ { "asset": { "height": 900, "mimeType": "image/jpeg", "size": 21000, "url": "https://livingdocs.io/img.jpg", "width": 1600 }, "createdAt": "2020-12-27T09:19:00.928Z", "id": "asze63i9", "mediaType": "image", "metadata": { "title": "An Image" }, "updatedAt": "2020-12-27T09:19:00.928Z", "version": 1 }, { "asset": { "height": 900, "mimeType": "image/jpeg", "size": 21000, "url": "https://livingdocs.io/img2.jpg", "width": 1600 }, "createdAt": "2020-12-27T09:19:00.928Z", "id": "2er11b3i", "mediaType": "image", "metadata": { "title": "An Other Image" }, "updatedAt": "2020-12-27T09:19:00.928Z", "version": 1 } ] } } }, "schema": { "properties": { "results": { "items": { "$ref": "#/components/schemas/MediaLibraryEntry" }, "type": "array" } }, "type": "object" } } }, "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:write" ] } ], "summary": "Import Media Library Entries", "tags": [ "Imports" ] } }, "/api/2026-05/import/videos": { "post": { "description": "The video import does both create and update videos. The import remembers the `externalId` / `systemName` pair and if an import matches an existing pair, it will update (Hint: consider how to rebuild the `externalId` when you want to update videos). The video import in Livingdocs is asynchronous. You post a batch of videos that you want to import and get back an id with which you can query later to get your result.", "operationId": "importVideos", "requestBody": { "content": { "application/json": { "examples": { "importSingleVideo": { "value": [ { "context": { "myIdentifier": "some-identifier-sent-to-the-webhook" }, "systemName": "identifier-for-your-system", "videos": [ { "fileName": "foo", "id": "123abc", "metadata": { "credit": "LC", "title": "sample video" }, "url": "https://www.learningcontainer.com/wp-content/uploads/2020/05/sample-mp4-file.mp4" } ], "webhook": "https://my-domain.com/webhooks/video-import" } ] } }, "schema": { "properties": { "context": { "description": "An object that is passed as context in the body of the request to the webhook. Limited to 8192 Bytes.", "type": "object" }, "systemName": { "description": "Identifier for the system you are importing from, e.g. an archive", "type": "string" }, "videos": { "description": "An array of videos to import. Each entry is an object with the following keys, all of which are required:", "items": { "properties": { "fileName": { "description": "the title that the video should get in livingdocs", "type": "string" }, "id": { "description": "a unique id (stored as externalId in Livingdocs) that identifies the document on your end, must be unique within your project.", "type": "string" }, "metadata": { "description": "An object of metadata according to your project config", "type": "object" }, "url": { "description": "a URL to an video file, no data urls allowed, must be an video, allowed types: (TODO)", "format": "uri", "type": "string" } }, "required": [ "id", "url", "fileName", "metadata" ], "type": "object" }, "type": "array" }, "webhook": { "description": "Endpoint at the importing system that gets notified by POST when import job is done. Notification contains the id of the import job, the state and an overview.", "format": "uri", "type": "string" } }, "required": [ "systemName", "videos" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": { "id": "25bzj8j" } } }, "schema": { "type": "object" } } }, "description": "ok" }, "429": { "content": { "application/json": { "examples": { "usageLimitExceeded": { "value": { "error": "Usage Limit Exceeded", "error_details": { "message": "Your plan does not allow you to upload more than 100 per day.\n You already uploaded 99 in the last 24 hours and are trying to upload 10 more.\n Please try again later." }, "status": 429 } } }, "schema": { "items": { "type": "object" }, "type": "array" } } }, "description": "Usage Limit Exceeded" } }, "security": [ { "bearerAuth": [ "public-api:write" ] } ], "summary": "Import Videos", "tags": [ "Imports" ] } }, "/api/2026-05/import/videos/status": { "get": { "description": "You can use this endpoint to check for the status and/or result of a video import.", "operationId": "getVideoImportStatus", "parameters": [ { "description": "The id that Livingdocs provided you for your prior call to `/import/videos`", "in": "query", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "failed": { "value": { "finished": true, "id": "098shjhv9", "state": "failed" } }, "inProgress": { "value": { "finished": false, "id": "243kdc", "startedAt": "2020-01-01 13:45:12", "state": "started" } }, "success": { "value": { "finished": true, "id": "25bzj8j", "state": "success", "videos": [ { "externalId": "external-unique-id-123", "state": "success", "systemName": "identifier-for-your-system", "video": { "mediaId": "jjiwhsf23kdk", "mimeType": "video/mp4", "originalUrl": "https://livingdocs-videos.imgix.net/2019/11/21/a209790e-1549-46d9-b3c7-cefe28c7ea99.mp4" } }, { "externalId": "external-unique-id-234", "reason": "already exists", "state": "skipped", "systemName": "identifier-for-your-system", "video": { "mediaId": "jjiwhsf23wer", "mimeType": "video/mp4", "originalUrl": "https://livingdocs-videos.imgix.net/2019/11/21/a209790e-1549-46d9-b3c7-cefe28c7ea99.mp4" } }, { "externalId": "external-unique-id-345", "reason": "Could not upload video", "state": "failed", "systemName": "identifier-for-your-system" } ] } } }, "schema": { "type": "object" } } }, "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:write" ] } ], "summary": "Check Import Status for Videos", "tags": [ "Imports" ] } }, "/api/2026-05/mediaLibrary": { "get": { "description": "Fetch multiple Media Library Entries by their `id` or `externalId`", "operationId": "getMediaLibraryEntries", "parameters": [ { "description": "Ids of a Media Library entries", "examples": { "multiple": { "value": "gxMMLV1fc-cm,f4jH1hyijDiF" } }, "in": "query", "name": "ids", "schema": { "type": "string" } }, { "description": "Must be unique in combination with systemName", "examples": { "externalId": { "value": "6hedie82" } }, "in": "query", "name": "externalIds", "schema": { "type": "string" } }, { "description": "A string identifiyng the external system where the asset is imported from. It is recommended that you always set this value and it is required if you provide an externalId.", "examples": { "systemName": { "value": "externalSystem" } }, "in": "query", "name": "systemName", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "externalSystem": { "value": { "results": [ { "asset": { "height": 900, "mimeType": "image/jpeg", "size": 21000, "url": "https://livingdocs.io/img.jpg", "width": 1600 }, "createdAt": "2020-12-27T09:19:00.928Z", "externalId": "ex-1", "id": "a77ei8nm", "mediaType": "image", "metadata": { "title": "An Image" }, "systemName": "externalSystem", "updatedAt": "2020-12-27T09:19:00.928Z", "version": 1 } ] } }, "success": { "value": { "results": [ { "asset": { "height": 900, "mimeType": "image/jpeg", "size": 21000, "url": "https://livingdocs.io/img.jpg", "width": 1600 }, "createdAt": "2020-12-27T09:19:00.928Z", "id": "asze63i9", "mediaType": "image", "metadata": { "title": "An Image" }, "updatedAt": "2020-12-27T09:19:00.928Z", "version": 1 }, { "asset": { "height": 900, "mimeType": "image/jpeg", "size": 21000, "url": "https://livingdocs.io/img2.jpg", "width": 1600 }, "createdAt": "2020-12-27T09:19:00.928Z", "id": "2er11b3i", "mediaType": "image", "metadata": { "title": "An Other Image" }, "updatedAt": "2020-12-27T09:19:00.928Z", "version": 1 } ] } } }, "schema": { "properties": { "results": { "items": { "$ref": "#/components/schemas/MediaLibraryEntry" }, "type": "array" } }, "type": "object" } } }, "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Get Media Library Entries", "tags": [ "Media Library" ] } }, "/api/2026-05/mediaLibrary/serve-image/{key}": { "get": { "description": "This endpoint delivers an image in its original dimensions, provided the asset remains valid (i.e., not revoked or marked as invalid).\nIt is designed to serve as a reliable source for image proxies or resizing services, ensuring only authorized and valid images are accessible.\n", "operationId": "mediaLibraryServeImage", "parameters": [ { "description": "The unique key of the image asset in the media library", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "image/*": { "schema": { "format": "binary", "type": "string" } } }, "description": "OK" }, "403": { "content": { "application/json": { "examples": { "revokedOrInvalid": { "value": { "error": "Forbidden", "error_details": { "message": "The requested image is revoked or marked as invalid" }, "status": 403 } } }, "schema": { "properties": { "error": { "type": "string" }, "error_details": { "properties": { "message": { "type": "string" } }, "type": "object" }, "status": { "type": "number" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "imageNotFound": { "value": { "error": "Not Found", "error_details": { "message": "No image found." }, "status": 404 } } }, "schema": { "properties": { "error": { "type": "string" }, "error_details": { "properties": { "message": { "type": "string" } }, "type": "object" }, "status": { "type": "number" } }, "type": "object" } } }, "description": "Not Found" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Serve Image", "tags": [ "Media Library" ] } }, "/api/2026-05/mediaLibrary/{id}": { "get": { "description": "Fetch a Media Library Entries by its `id`", "operationId": "getMediaLibraryEntryById", "parameters": [ { "description": "Id of a Media Library entry", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": { "asset": { "height": 900, "mimeType": "image/jpeg", "size": 21000, "url": "https://livingdocs.io/img.jpg", "width": 1600 }, "createdAt": "2020-12-27T09:19:00.928Z", "id": "asze63i9", "mediaType": "image", "metadata": { "title": "An Image" }, "updatedAt": "2020-12-27T09:19:00.928Z", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/MediaLibraryEntry" } } }, "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Get a Single Media Library Entry", "tags": [ "Media Library" ] }, "patch": { "description": "Patch a Media Library Entries by its `id`", "operationId": "updateMediaLibraryEntry", "parameters": [ { "description": "Id of a Media Library entry", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "post": { "value": { "patches": [ { "operation": "setMetadataProperty", "propertyName": "title", "value": "updated title" }, { "operation": "replaceAsset", "value": { "filename": "my-new-file.png", "height": 800, "key": "2021/11/23/my-new-file.png", "mimeType": "image/png", "size": 10000, "url": "https: //example.com/my-new-file.png", "width": 1000 } }, { "note": "Case #1", "operation": "revokeAsset" }, { "operation": "unrevokeAsset" }, { "operation": "archive" }, { "locale": "en", "operation": "removeAsset" }, { "operation": "addUsageLogEntry", "value": { "params": {}, "publicationDate": "2026-05-01T11:00:00.000Z", "purpose": "print", "state": "pending", "url": "http://localhost" } }, { "oldValue": {}, "operation": "updateUsageLogEntry", "usageLogEntryId": "g1x419UgQSS5", "value": { "params": { "medium": "Paper" }, "publicationDate": "2026-05-01T11:00:00.000Z", "purpose": "print", "state": "confirmed", "url": "http://localhost" } }, { "operation": "removeUsageLogEntry", "usageLogEntryId": "g1x419UgQSS5" } ], "version": 1 } } }, "schema": { "properties": { "patches": { "items": { "properties": { "operation": { "type": "string" } }, "type": "object" }, "type": "array" }, "preserveUpdatedAt": { "default": false, "description": "When true, the entry's updated_at timestamp is not modified.", "type": "boolean" }, "version": { "type": "number" } }, "type": "object" } } } }, "responses": { "200": { "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:write" ] } ], "summary": "Patch a Single Media Library Entry", "tags": [ "Media Library" ] } }, "/api/2026-05/mediaLibrary/{id}/usageLog": { "get": { "description": "Fetch the Usage Log of a Media Library Entry", "operationId": "getMediaLibraryEntryUsageLog", "parameters": [ { "description": "Id of a Media Library entry", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": { "results": [ { "documentId": 121, "id": "g6Hmp49Y", "params": { "medium": "Internet" }, "publicationDate": "2026-04-02T13:34:26.353Z", "publicationId": 110, "purpose": "web", "reportingDate": "2026-04-02T13:34:30.263Z", "state": "confirmed", "url": "https://example.com/article/slug-121" } ] } } }, "schema": { "properties": { "results": { "items": { "properties": { "documentId": { "type": "integer" }, "id": { "type": "string" }, "params": { "type": "object" }, "publicationDate": { "format": "date-time", "type": "string" }, "publicationId": { "type": "integer" }, "purpose": { "type": "string" }, "reportingDate": { "format": "date-time", "type": "string" }, "state": { "enum": [ "pending", "confirmed" ], "type": "string" }, "url": { "format": "url", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Get the Usage Log of a Media Library Entry", "tags": [ "Media Library" ] } }, "/api/2026-05/mediaLibrary/{mediaId}/incomingDocumentReferences": { "get": { "description": "Added in: release-2022-03", "operationId": "getIncomingDocumentReferencesForMediaLibraryEntry", "parameters": [ { "in": "path", "name": "mediaId", "required": true, "schema": { "type": "string" } }, { "description": "A limit for how much published documents to retrieve. Defaults to 100. Max. 100.", "examples": { "default": { "value": 100 } }, "in": "query", "name": "limit", "schema": { "type": "number" } }, { "description": "An offset into the query. Useful when getting more than 100 results (pagination).", "examples": { "default": { "value": 0 } }, "in": "query", "name": "offset", "schema": { "type": "number" } }, { "description": "The `cursor` provided in the response can be passed back for pagination instead of using `offset`.", "examples": { "cursor": { "value": "eyJhIjpbIjE3NjUyNjIxODYuMjgyIiw2NCw2NF19" } }, "in": "query", "name": "?after", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": { "cursor": "eyJhIjpbIjE3NjUyNjIxODYuMjgyIiw2NCw2NF19", "results": [ { "id": 2, "references": [ { "componentId": "doc-1ev8345oj0", "componentName": "image", "directiveName": "image", "id": "9fKagDCiN6sb", "location": "image-directive", "type": "image" }, { "id": "9fKagDCiN6sb", "location": "metadata", "propertyName": "teaserImage", "type": "image" } ] }, { "id": 3, "references": [ { "componentId": "doc-1euq8lq1o0", "componentName": "image", "directiveName": "image", "id": "9fKagDCiN6sb", "location": "image-directive", "type": "image" }, { "id": "9fKagDCiN6sb", "location": "metadata", "propertyName": "teaserImage", "type": "image" } ] } ], "total": 3 } } }, "schema": { "properties": { "cursor": { "type": "string" }, "results": { "items": { "properties": { "id": { "type": "integer" }, "references": { "items": { "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "total": { "type": "integer" } }, "type": "object" } } }, "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Get Incoming Publication References for a Media Library Entry", "tags": [ "Media Library" ] } }, "/api/2026-05/mediaLibrary/{mediaId}/incomingMediaReferences": { "get": { "description": "Added in: release-2022-03", "operationId": "getIncomingMediaReferencesForMediaLibraryEntry", "parameters": [ { "in": "path", "name": "mediaId", "required": true, "schema": { "type": "string" } }, { "description": "A limit for how much published documents to retrieve. Defaults to 100. Max. 100.", "examples": { "default": { "value": 100 } }, "in": "query", "name": "limit", "schema": { "type": "number" } }, { "description": "An offset into the query. Useful when getting more than 100 results (pagination).", "examples": { "default": { "value": 0 } }, "in": "query", "name": "offset", "schema": { "type": "number" } }, { "description": "The `cursor` provided in the response can be passed back for pagination instead of using `offset`.", "examples": { "cursor": { "value": "eyJhIjpbIjE3NjUyNjIxODYuMjgyIiw2NCw2NF19" } }, "in": "query", "name": "?after", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": { "cursor": "eyJhIjpbIjE3NjUyNjIxODYuMjgyIiw2NCw2NF19", "results": [ { "id": "B1LPgANhJFpo", "references": [ { "id": "9fKagDCiN6sb", "location": "metadata", "propertyName": "imageLink", "type": "image" } ] } ], "total": 2 } } }, "schema": { "properties": { "cursor": { "type": "string" }, "results": { "items": { "properties": { "id": { "type": "integer" }, "references": { "items": { "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "total": { "type": "integer" } }, "type": "object" } } }, "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Get Incoming Media References for a Media Library Entry", "tags": [ "Media Library" ] } }, "/api/2026-05/projectConfig": { "get": { "description": "Get Project Configuration", "operationId": "getProjectConfig", "responses": { "200": { "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:config:read" ] } ], "summary": "Get Project Configuration", "tags": [ "Project" ] } }, "/api/2026-05/publicationEvents": { "get": { "description": "Get Publication Events for the default channel", "operationId": "getPublicationEvents", "parameters": [ { "description": "Number of events to return. Default: 100. Highest limit: 1000.", "examples": { "default": { "value": 100 } }, "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Returns the events in reverse order, starting at the biggest id.", "examples": { "reverse": { "value": false } }, "in": "query", "name": "reverse", "schema": { "type": "boolean" } }, { "description": "Comma separated list of content types to use as filter.", "in": "query", "name": "contentTypes", "schema": { "type": "string" } }, { "description": "Comma separated list of document types to use as filter. \n\nCan be one of `article`, `page`, `data-record`.", "in": "query", "name": "documentTypes", "schema": { "type": "string" } }, { "deprecated": true, "description": "**Deprecated**: Please use `id.gte` instead.\n\nReturn matching events after this event id.", "in": "query", "name": "after", "schema": { "type": "integer" } }, { "description": "Filter by event id range.\n\n**Supported filters**: `id.gte`, `id.gt`, `id.lte`, `id.lt`.\n\n**Example**: To retrieve all events since you’ve fetched the last entry, use `?limit=1000\u0026id.gt=40000`", "in": "query", "name": "id.gte", "schema": { "type": "string" } }, { "in": "query", "name": "id.gt", "schema": { "type": "string" } }, { "in": "query", "name": "id.lte", "schema": { "type": "string" } }, { "in": "query", "name": "id.lt", "schema": { "type": "string" } }, { "description": "Filter by event date range.\n\n**Supported filters**: `createdAt.gte`, `createdAt.gt`, `createdAt.lte`, `createdAt.lt`.\n\n**Example**: To retrieve all events since a specific timestamp, use `?limit=1000\u0026createdAt.gte=2021-05-01T00:00:00.000Z`", "in": "query", "name": "createdAt.gte", "schema": { "type": "string" } }, { "in": "query", "name": "createdAt.gt", "schema": { "type": "string" } }, { "in": "query", "name": "createdAt.lte", "schema": { "type": "string" } }, { "in": "query", "name": "createdAt.lt", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": { "results": [ { "channelId": 53, "createdAt": "2016-12-27T09:19:00.928Z", "documentId": 7892, "documentType": "article", "eventType": "publish", "id": 910, "projectId": 30, "publicationId": 1066 }, { "channelId": 53, "createdAt": "2016-12-27T09:32:10.898Z", "documentId": 7892, "documentType": "article", "eventType": "unpublish", "id": 988, "projectId": 30, "publicationId": 1100 }, { "channelId": 53, "createdAt": "2016-12-27T09:33:05.010Z", "documentId": 8005, "documentType": "article", "eventType": "publish", "id": 990, "projectId": 30, "publicationId": 1131 }, { "channelId": 53, "createdAt": "2016-12-27T09:33:31.517Z", "documentId": 7892, "documentType": "article", "eventType": "update", "id": 1011, "projectId": 30, "publicationId": 1394 } ] } } }, "schema": { "properties": { "results": { "items": { "properties": { "channelId": { "type": "integer" }, "createdAt": { "format": "date-time", "type": "string" }, "documentId": { "type": "integer" }, "documentType": { "type": "string" }, "eventType": { "type": "string" }, "id": { "type": "integer" }, "projectId": { "type": "integer" }, "publicationId": { "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Publication Events", "tags": [ "Publications" ] } }, "/api/2026-05/publications/search": { "get": { "description": "Search Publications", "operationId": "searchPublications", "parameters": [ { "description": "Search term to perform a full-text search with. For exact word matches use “, e.g. `search=“Ukulele”`", "examples": { "search": { "value": "some sentence to search" } }, "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma separated list of content-types for which documents should be found. Content types are concatenated with OR. Example: 'regular,author'", "examples": { "regularAndAuthor": { "value": "regular,author" } }, "in": "query", "name": "contentTypes", "schema": { "type": "string" } }, { "description": "Comma separated list of category ids for which documents should be found. Categories are concatenated with OR. Example: 'sport,fashion'", "examples": { "categories": { "value": "sport,fashion" } }, "in": "query", "name": "categories", "schema": { "type": "string" } }, { "description": "Comma separated list of languages for which documents should be found. Languages are concatenated with OR. Example: 'en,de'", "examples": { "enAndDe": { "value": "en,de" } }, "in": "query", "name": "languages", "schema": { "type": "string" } }, { "description": "A GroupId used to fetch all translations of a document Using the ?languages param a document in a specific language can be fetched. Example: `?languageGroupId=47?language=de`", "examples": { "languageGroupId": { "value": "1jfasfdu" } }, "in": "query", "name": "languageGroupId", "schema": { "type": "string" } }, { "description": "A JSON string which follows the search filters query DSL.", "examples": { "termFilter": { "value": "[{\"key\":\"metadata.title\",\"term\":\"My Title\"}]" } }, "in": "query", "name": "filters", "schema": { "type": "string" } }, { "description": "Comma separated list of sort properties. Any of the filter fields can be used, and also sortDate, which can be defined using the publication index config, or will be the Visible Publication Date. Most metadata properties can be used to sort, but not those indexed as 'text' or 'boolean'. The sort order can be reversed by prefixing the property with a `-`. Documents which don't have an indexed value will appear at the end of the results.", "examples": { "descendingDocumentId": { "value": "-documentId" }, "sortDate": { "value": "sortDate" } }, "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Filters which (comma separated) properties are included in the response. Defaults to `systemdata,metadata,content` (no renditions). Use `id` if you only want to retrieve the ids of the published documents. Useful (and faster) if you are fully synchronizing your frontend with the publication events.", "examples": { "default": { "value": "systemdata,metadata,content" } }, "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "A limit for how much published documents to retrieve. Defaults to 10. Max. 100.", "examples": { "default": { "value": 10 } }, "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 0, "type": "integer" } }, { "description": "An offset into the query. Useful when getting more than 100 results (pagination)", "examples": { "default": { "value": 0 } }, "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "description": "The `cursor` provided in the response can be passed back for pagination instead of using `offset`.", "examples": { "cursor": { "value": "eyJhIjpbIjE3NjUyNjIxODYuMjgyIiw2NCw2NF19" } }, "in": "query", "name": "?after", "schema": { "type": "string" } }, { "description": "Provides a way to opt out of component filtering and return all content regardless of whether each component passes the conditional checks.", "examples": { "default": { "value": false } }, "in": "query", "name": "ignoreComponentConditions", "schema": { "type": "boolean" } }, { "description": "JSON stringified object which contains the component conditions you would like to apply.", "examples": { "atASpecificTime": { "value": "{\"dateTime\":\"2024-02-14T17:25:10.391Z\"}" } }, "in": "query", "name": "componentConditions", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": { "cursor": "eyJhIjpbIjE3NjUyNjIxODYuMjgyIiw2NCw2NF19", "results": [ { "content": [ { "component": "head", "content": { "text": "some lead", "title": "a title" }, "id": "doc-1b8i1ksh10", "identifier": "timeline.head" }, { "component": "normal", "content": { "caption": "my caption" }, "id": "doc-1b8i1ksh20", "identifier": "timeline.normal", "styles": { "position": "left" } }, { "component": "p", "content": { "text": "first paragraph" }, "id": "doc-1b8i1ksh30", "identifier": "timeline.p" }, { "component": "p", "content": { "text": "second paragraph" }, "id": "doc-1b8i1me1d0", "identifier": "timeline.p" } ], "metadata": { "dependencies": {}, "description": "some lead", "title": "a title" }, "references": [ { "id": "YbzTpusGyJtF", "location": "metadata", "propertyName": "language", "type": "language-group" } ], "systemdata": { "channelId": 1, "contentType": "article", "design": { "name": "timeline", "version": "1.1.0" }, "documentId": 1, "documentType": "article", "firstPublicationDate": "2022-03-16T14:08:11.000Z", "layout": "regular", "projectId": 1, "publicationId": 1, "significantPublicationDate": "2022-10-26T07:25:00.000Z", "updatedAt": "2022-10-30T16:32:04.170Z", "visiblePublicationDate": "2022-10-27T06:00:00.000Z" } }, { "content": [ { "component": "head", "content": { "text": "some lead", "title": "a title" }, "id": "doc-1b8i1ksh10", "identifier": "timeline.head" }, { "component": "normal", "content": { "caption": "my caption" }, "id": "doc-1b8i1ksh20", "identifier": "timeline.normal", "styles": { "position": "left" } }, { "component": "p", "content": { "text": "first paragraph" }, "id": "doc-1b8i1ksh30", "identifier": "timeline.p" }, { "component": "p", "content": { "text": "second paragraph" }, "id": "doc-1b8i1me1d0", "identifier": "timeline.p" } ], "metadata": { "dependencies": {}, "description": "some other lead", "title": "another title" }, "references": [ { "id": "YbzTpusGyJtF", "location": "metadata", "propertyName": "language", "type": "language-group" } ], "systemdata": { "channelId": 1, "contentType": "article", "design": { "name": "timeline", "version": "1.1.0" }, "documentId": 2, "documentType": "article", "firstPublicationDate": "2022-03-16T14:08:11.000Z", "layout": "regular", "projectId": 1, "publicationId": 5, "significantPublicationDate": "2022-10-26T07:25:00.000Z", "updatedAt": "2022-10-30T16:32:04.170Z", "visiblePublicationDate": "2022-10-27T06:00:00.000Z" } } ], "total": 3 } } }, "schema": { "properties": { "cursor": { "type": "string" }, "results": { "items": { "properties": { "content": { "$ref": "#/components/schemas/Content" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "references": { "$ref": "#/components/schemas/References" }, "systemdata": { "$ref": "#/components/schemas/Systemdata" } }, "type": "object" }, "type": "array" }, "total": { "type": "integer" } }, "type": "object" } } }, "description": "ok" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Search Publications", "tags": [ "Publications" ] } }, "/api/2026-05/retresco/re-enrich": { "post": { "description": "This hook should be used on Retresco when enabling the re-enrich feature to trigger asynchronous document enrichment.", "operationId": "retrescoReenrich", "requestBody": { "content": { "application/json": { "examples": { "reEnrichWithIds": { "value": { "doc_ids": [ 1, 2, 3, 4 ] } } }, "schema": { "properties": { "doc_ids": { "items": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "type": "array" } }, "required": [ "doc_ids" ], "type": "object" } } } }, "responses": { "200": { "description": "doc_ids list accepted to process" } }, "security": [ { "bearerAuth": [ "retresco" ] } ], "summary": "Retresco re-enrich Webhook", "tags": [ "Retresco" ] } }, "/api/2026-05/routing/resolve": { "get": { "description": "You need to activate the Categories / Routing Feature in the Project Config in order to resolve paths to your documents. Routing is a quite advanced topic and the examples only work with a default configuration. Find more [here](https://docs.livingdocs.io/guides/organisation/routing-system/).", "operationId": "resolveDocumentPath", "parameters": [ { "description": "Path to the document.\n\n**Example 1:** A page with a category `/news` can be found with `?path=/news.html`.\n\n**Example 2:** A document with id 10, with category /news and a slug `hello` can be found with `?path=/magazin/hello-10.html`.", "in": "query", "name": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "value": [ { "resource": { "id": 173, "statusCode": 200 }, "type": "document" } ] } } } }, "description": "OK" }, "301": { "content": { "application/json": { "examples": { "movedPermanently": { "value": [ { "path": "/path/to/redirect", "resource": { "statusCode": 301 }, "type": "redirect" } ] } } } }, "description": "Moved Permanently" }, "404": { "content": { "application/json": { "examples": { "notFound": { "value": { "error": "Not Found", "status": 404 } } } } }, "description": "Not Found" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Resolve a Path to a Document", "tags": [ "Routing" ] } }, "/api/2026-05/sitemaps/entries": { "get": { "description": "Get a Sitemap's Entries", "operationId": "getSitemapEntries", "parameters": [ { "description": "Base url of the delivery host. `?baseUrl=https://livingdocs.io/`", "examples": { "baseURL": { "value": "https://livingdocs.io/" } }, "in": "query", "name": "baseUrl", "required": true, "schema": { "type": "string" } }, { "description": "Date for the specific month matching the schema from the sitemap index file. Example: `?date=2021-06` or `?date=2021-06.2`", "in": "query", "name": "date", "required": true, "schema": { "type": "string" } }, { "description": "A comma-separated list of contentTypes to include in the sitemap. Example: `?contentTypes=regular,pages`", "examples": { "regularAndPagesContentTypes": { "value": "regular,pages" } }, "in": "query", "name": "contentTypes", "schema": { "type": "string" } }, { "description": "Optional sitemap entry page size. Default 20000", "examples": { "default": { "value": "20000" } }, "in": "query", "name": "entriesPerPage", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/xml": { "examples": { "success": { "externalValue": "https://livingdocsio.github.io/openapi/examples/sitemap-entries.xml", "summary": "Sitemap example" } } } }, "description": "Sitemap" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Get a Sitemap's Entries", "tags": [ "Sitemaps" ] } }, "/api/2026-05/sitemaps/index": { "get": { "description": "Get a Sitemap's Index", "operationId": "getSitemapIndex", "parameters": [ { "description": "Base url of the delivery host", "in": "query", "name": "baseUrl", "required": true, "schema": { "type": "string" } }, { "description": "A comma-separated list of contentTypes to include in the sitemap. Example: `?contentTypes=regular,pages`", "examples": { "regularAndPagesContentTypes": { "value": "regular,pages" } }, "in": "query", "name": "contentTypes", "schema": { "type": "string" } }, { "description": "Optional sitemap entry page size. Default 20000", "examples": { "default": { "value": "20000" } }, "in": "query", "name": "entriesPerPage", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/xml": { "examples": { "success": { "externalValue": "https://livingdocsio.github.io/openapi/examples/sitemap-index.xml", "summary": "Sitemap example" } } } }, "description": "Sitemap" } }, "security": [ { "bearerAuth": [ "public-api:read" ] } ], "summary": "Get a Sitemap's Index", "tags": [ "Sitemaps" ] } } }, "servers": [ { "description": "localhost", "url": "http://localhost:9090" }, { "description": "downstream", "url": "{protocol}://{hostname}", "variables": { "hostname": { "default": "example.com" }, "protocol": { "default": "https", "enum": [ "http", "https" ] } } } ], "tags": [ { "description": "Project", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/project/" }, "name": "Project" }, { "description": "Execute commands on documents", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/command-api/" }, "name": "Document Command API" }, { "description": "", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/composition-api/" }, "name": "Composition" }, { "description": "Publications", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/publications/" }, "name": "Publications" }, { "description": "Drafts", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/drafts/" }, "name": "Drafts" }, { "description": "", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/document-lists/" }, "name": "Document Lists" }, { "description": "", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/document-categories/" }, "name": "Document Categories" }, { "description": "Media Library", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/media-library/" }, "name": "Media Library" }, { "description": "Imports", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/imports/" }, "name": "Imports" }, { "description": "Sitemaps", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/sitemaps/" }, "name": "Sitemaps" }, { "description": "Menus", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/menus/" }, "name": "Menus" }, { "description": "Routing", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/routing/" }, "name": "Routing" }, { "description": "", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/add-delivery-status/" }, "name": "Add Delivery Status" }, { "description": "Check API status", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/health/" }, "name": "Health" }, { "description": "Retresco Webhook", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/guides/integrations/retresco/" }, "name": "Retresco" } ] }