{ "openapi": "3.0.3", "info": { "description": "This is to quickly test the Livingdocs Public API. First create a project on [Livingdocs](edit.livingdocs.io). Then create a API token for that project. Use the token to authorize your requests. You can find out more about Livingdocs [http://livingdocs.io](http://livingdocs.io). ", "version": "release-2024-01", "title": "Livingdocs Public API", "termsOfService": "http://livingdocs.io/terms/", "contact": { "email": "team@livingdocs.io" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, "tags": [ { "name": "Project", "description": "Project", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/project/" } }, { "name": "Document Command API", "description": "Execute commands on documents", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/command-api/" } }, { "name": "Composition", "description": "", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/composition-api/" } }, { "name": "Publications", "description": "Publications", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/publications/" } }, { "name": "Drafts", "description": "Drafts", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/drafts/" } }, { "name": "Document Lists", "description": "", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/document-lists/" } }, { "name": "Document Categories", "description": "", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/document-categories/" } }, { "name": "Media Library", "description": "Media Library", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/media-library/" } }, { "name": "Imports", "description": "Imports", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/imports/" } }, { "name": "Sitemaps", "description": "Sitemaps", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/sitemaps/" } }, { "name": "Menus", "description": "Menus", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/menus/" } }, { "name": "Routing", "description": "Routing", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/routing/" } }, { "name": "Add Delivery Status", "description": "", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/add-delivery-status/" } }, { "name": "Health", "description": "Check API status", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/reference/public-api/health/" } }, { "name": "Retresco", "description": "Retresco Webhook", "externalDocs": { "description": "Docs", "url": "https://docs.livingdocs.io/guides/integrations/retresco/" } } ], "paths": { "/api/v1/project": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Project" ], "operationId": "getProjectionConfiguration", "summary": "Get Project Configuration (deprecated release-2023-03)", "description": "Your AccessToken is valid for a single project. This endpoint tells you the details and configuration of this project.", "responses": { "200": { "description": "ok" } } } }, "/api/v1/channels": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Project" ], "operationId": "getAllChannels", "description": "Get Default Channel Configuration (deprecated release-2023-03)", "summary": "Get Default Channel Configuration (deprecated release-2023-03)", "responses": { "200": { "description": "ok" } } } }, "/api/v1/projectConfig": { "get": { "security": [ { "bearerAuth": [ "public-api:config:read" ] } ], "tags": [ "Project" ], "summary": "Get Project Configuration", "description": "Get Project Configuration", "operationId": "getProjectConfig", "responses": { "200": { "description": "ok" } } } }, "/api/v1/channels/{channelHandle}": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Project" ], "operationId": "getChannelConfigurationByChannelHandle", "summary": "Get Channel Configuration (deprecated 2023-03)", "description": "Get Channel Configuration (deprecated 2023-03)", "deprecated": true, "parameters": [ { "name": "channelHandle", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "ok" } } } }, "/api/v1/design": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Project" ], "operationId": "getCurrentDesign", "description": "Get Current Design", "summary": "Get Current Design", "responses": { "200": { "description": "ok" } } } }, "/api/v1/design/{designVersion}": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Project" ], "operationId": "getDesignByVersion", "description": "Get Specific Design", "summary": "Get Specific Design", "parameters": [ { "name": "designVersion", "in": "path", "required": true, "schema": { "type": "string", "example": "" } } ], "responses": { "200": { "description": "ok" } } } }, "/api/v1/publications/search": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Publications" ], "operationId": "searchPublications", "summary": "Search Publications", "description": "Search Publications", "parameters": [ { "name": "search", "description": "Search term to perform a full-text search with. For exact word matches use “, e.g. `search=“Ukulele”`", "in": "query", "schema": { "type": "string", "example": "" } }, { "name": "categories", "description": "Comma separated list of category ids for which documents should be found. Categories are concatenated with OR. Example: `sport,fashion`", "in": "query", "schema": { "type": "string", "example": "sport,fashion" } }, { "name": "languages", "description": "Comma separated list of languages for which documents should be found. Languages are concatenated with OR. Example: `en,de`", "in": "query", "schema": { "type": "string", "example": "en,de" } }, { "name": "languageGroupId", "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`", "in": "query", "schema": { "type": "string", "example": "" } }, { "name": "contentTypes", "description": "Comma separated list of content-types for which documents should be found. Content types are concatenated with OR. Example: `article,author`", "in": "query", "schema": { "type": "string", "example": "regular,author" } }, { "name": "filters", "description": "A JSON string which follows the search filters query DSL.", "in": "query", "schema": { "type": "string", "example": "[{\"key\":\"metadata.title\",\"term\":\"My Title\"}]" } }, { "name": "sort", "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.", "in": "query", "schema": { "type": "string", "example": "sortDate,-documentId" } }, { "name": "fields", "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.", "in": "query", "schema": { "type": "string", "example": "systemdata,metadata,content" } }, { "name": "limit", "description": "A limit for how much published documents to retrieve. Defaults to 10. Max. 100.", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100, "example": 10 } }, { "name": "offset", "description": "An offset into the query. Useful when getting more than 100 results (pagination)", "in": "query", "schema": { "type": "integer", "example": 0 } } ], "responses": { "200": { "description": "ok" } } } }, "/api/v1/document-lists/{id}": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Document Lists" ], "operationId": "getDocumentListById", "summary": "Get List by Id", "description": "Get List by Id", "parameters": [ { "name": "id", "description": "List Id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "reverse", "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)", "in": "query", "schema": { "type": "boolean", "example": false } }, { "name": "fields", "description": "Filters which (comma separated) document properties are included in the response. Defaults to `systemdata,metadata` also accepts `content` (no renditions).", "in": "query", "schema": { "type": "string", "example": "systemdata,metadata,content" } }, { "name": "limit", "description": "A limit for how much documents to resolve for the requested list. Defaults to 100. Max. 100.", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100, "example": 100 } } ], "responses": { "200": { "description": "ok" } } } }, "/api/v1/document-lists": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Document Lists" ], "operationId": "getAndFilterDocumentLists", "description": "Get Lists", "summary": "Get Lists", "parameters": [ { "name": "name", "description": "Filters the result set and allows searching by list name.", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "description": "A limit for how much documents to resolve for the requested list. Defaults to 10. Max. 100.", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100, "example": 10 } }, { "name": "offset", "description": "An offset into the query. Useful when getting more than 100 results (pagination).", "in": "query", "schema": { "type": "integer", "example": 0 } } ], "responses": { "200": { "description": "ok" } } } }, "/api/v1/categories/{categoryId}": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Document Categories" ], "operationId": "getCategoryById", "summary": "Get a Category with all Information", "description": "You need to activate the Categories / Routing Feature in the Project Config in order to query categories.", "parameters": [ { "name": "categoryId", "description": "Id of a specific categories as fetched from the /categories endpoint.", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "inheritMetadata", "description": "If set to `true` will inherit (but not overwrite) metadata properties from all parents Inheritance depth is limited to 20.", "in": "query", "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "path": { "type": "string" }, "metadata": { "type": "object" } } }, "example": { "id": "123abc", "label": "Sport", "path": "/sport", "metadata": { "adId": "sport-ads", "analyticsCode": "sport-analytics" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": 400, "error": "Bad Request", "error_details": { "message": "Use of the category API requires a configurable channel. The project you requested uses a static configuration though." } } } } }, "500": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": 500, "error": "Bad Request", "error_details": { "message": "Inheritance queries can only be made up to a depth of 20." } } } } } } } }, "/api/v1/categories": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Document Categories" ], "operationId": "getAllCategories", "summary": "Get Categories for a Project", "description": "You need to activate the Categories / Routing Feature in the Project Config in order to query categories.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "path": { "type": "string" } } } }, "example": [ { "id": "category-id-1", "label": "Category 1", "path": "/category1" }, { "id": "category-id-2", "label": "Category 2", "path": "/category2", "parent": "category-id-1" }, { "id": "category-id-3", "label": "Category 3", "path": "/category3" } ] } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": 400, "error": "Bad Request", "error_details": { "message": "Use of the category API requires a configurable channel. The project you requested uses a static configuration though." } } } } } } } }, "/api/v1/mediaLibrary/{id}": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Media Library" ], "operationId": "getMediaLibraryEntryById", "summary": "Get a Single Media Library Entry", "description": "Fetch a Media Library Entries by its `id`", "parameters": [ { "name": "id", "description": "Id of a Media Library entry", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaLibraryEntry" }, "example": { "id": "asze63i9", "version": 1, "mediaType": "image", "asset": { "url": "https://livingdocs.io/img.jpg", "mimeType": "image/jpeg", "width": 1600, "height": 900, "size": 21000 }, "metadata": { "title": "An Image" }, "createdAt": "2020-12-27T09:19:00.928Z", "updatedAt": "2020-12-27T09:19:00.928Z" } } } } } }, "patch": { "security": [ { "bearerAuth": [ "public-api:write" ] } ], "tags": [ "Media Library" ], "operationId": "updateMediaLibraryEntry", "summary": "Patch a Single Media Library Entry", "description": "Patch a Media Library Entries by its `id`", "parameters": [ { "name": "id", "description": "Id of a Media Library entry", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "version": 1, "patches": [ { "operation": "setMetadataProperty", "propertyName": "title", "value": "updated title" }, { "operation": "replaceAsset", "value": { "key": "2021/11/23/my-new-file.png", "url": "https: //example.com/my-new-file.png", "size": 10000, "width": 1000, "height": 800, "filename": "my-new-file.png", "mimeType": "image/png" } }, { "operation": "revokeAsset" }, { "operation": "archive" }, { "operation": "removeAsset", "locale": "en" } ] }, "properties": { "version": { "type": "number" }, "patches": { "type": "array", "items": { "type": "object", "properties": { "operation": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "ok" } } } }, "/api/v1/mediaLibrary": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Media Library" ], "operationId": "getMediaLibraryEntries", "summary": "Get Media Library Entries", "description": "Fetch multiple Media Library Entries by their `id` or `externalId`", "parameters": [ { "name": "ids", "description": "Ids of a Media Library entries", "in": "query", "schema": { "type": "string", "example": "gxMMLV1fc-cm,f4jH1hyijDiF" } }, { "name": "externalIds", "description": "Must be unique in combination with systemName", "in": "query", "schema": { "type": "string", "example": "6hedie82" } }, { "name": "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.", "in": "query", "schema": { "type": "string", "example": "externalSystem" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "mediaLibraryEntries": { "type": "array", "items": { "$ref": "#/components/schemas/MediaLibraryEntry" } } }, "example": { "mediaLibraryEntries": [ { "id": "asze63i9", "version": 1, "mediaType": "image", "asset": { "url": "https://livingdocs.io/img.jpg", "mimeType": "image/jpeg", "width": 1600, "height": 900, "size": 21000 }, "metadata": { "title": "An Image" }, "createdAt": "2020-12-27T09:19:00.928Z", "updatedAt": "2020-12-27T09:19:00.928Z" }, { "id": "2er11b3i", "version": 1, "mediaType": "image", "asset": { "url": "https://livingdocs.io/img2.jpg", "mimeType": "image/jpeg", "width": 1600, "height": 900, "size": 21000 }, "metadata": { "title": "An Other Image" }, "createdAt": "2020-12-27T09:19:00.928Z", "updatedAt": "2020-12-27T09:19:00.928Z" } ] } } } } } } } }, "/api/v1/mediaLibrary/{mediaId}/incomingDocumentReferences": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Media Library" ], "operationId": "getIncomingDocumentReferencesForMediaLibraryEntry", "summary": "Get Incoming Publication References for a Media Library Entry", "description": "Added in: release-2022-03", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "description": "A limit for how much published documents to retrieve. Defaults to 100. Max. 100.", "in": "query", "schema": { "type": "number", "example": 100 } }, { "name": "offset", "description": "An offset into the query. Useful when getting more than 100 results (pagination).", "in": "query", "schema": { "type": "number", "example": 0 } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "example": [ { "id": 2, "references": [ { "id": "9fKagDCiN6sb", "type": "image", "location": "image-directive", "componentId": "doc-1ev8345oj0", "componentName": "image", "directiveName": "image" }, { "id": "9fKagDCiN6sb", "type": "image", "location": "metadata", "propertyName": "teaserImage" } ] }, { "id": 3, "references": [ { "id": "9fKagDCiN6sb", "type": "image", "location": "image-directive", "componentId": "doc-1euq8lq1o0", "componentName": "image", "directiveName": "image" }, { "id": "9fKagDCiN6sb", "type": "image", "location": "metadata", "propertyName": "teaserImage" } ] } ] } } } } } }, "/api/v1/mediaLibrary/{mediaId}/incomingMediaReferences": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Media Library" ], "operationId": "getIncomingMediaReferencesForMediaLibraryEntry", "summary": "Get Incoming Media References for a Media Library Entry", "description": "Added in: release-2022-03", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "description": "A limit for how much published documents to retrieve. Defaults to 100. Max. 100.", "in": "query", "schema": { "type": "number", "example": 100 } }, { "name": "offset", "description": "An offset into the query. Useful when getting more than 100 results (pagination).", "in": "query", "schema": { "type": "number", "example": 0 } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "example": [ { "id": "B1LPgANhJFpo", "references": [ { "id": "9fKagDCiN6sb", "type": "image", "location": "metadata", "propertyName": "imageLink" } ] } ] } } } } } }, "/api/v1/routing/resolve": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Routing" ], "operationId": "resolveDocumentPath", "summary": "Resolve a Path to a Document", "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/).", "parameters": [ { "name": "path", "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", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": [ { "type": "document", "resource": { "id": 173, "statusCode": 200 } } ] } } }, "301": { "description": "Moved Permanently", "content": { "application/json": { "example": [ { "type": "redirect", "path": "/path/to/redirect", "resource": { "statusCode": 301 } } ] } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "status": 404, "error": "Not Found" } } } } } } }, "/api/v1/menus/{channelHandle}": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Menus" ], "operationId": "getChannelMenus", "summary": "Get Menus for a Channel", "description": "Menu items can be of three `type`s:\n- uri for arbitrary URIs, mainly used for URLs\n- path for internal paths, such as when the menu item should link to an article or page\n- document is the same as path except it is used when routing is disabled", "parameters": [ { "name": "channelHandle", "description": "The handle of the channel for which you want to get the events.", "in": "path", "required": true, "schema": { "type": "string", "example": "web" } }, { "name": "handle", "description": "Handle of the menu to retrieve.", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "example": [ { "version": 8, "label": "My Menu", "maxDepth": 1, "nodes": [ { "id": "11111111-0601-4c2b-a3b5-4da19b6d3bde", "label": "My Index", "path": "/", "type": "uri", "target": "_self", "nodes": [ { "id": "22222222-0601-4c2b-a3b5-4da19b6d3bde", "documentId": 71, "label": "Other Page", "type": "path", "path": "/page/some-other-page", "nodes": [] } ] }, { "id": "33333333-0601-4c2b-a3b5-4da19b6d3bde", "label": "Arbitrary URL", "type": "uri", "uri": "http://example.com", "nodes": [] }, { "id": "44444444-0601-4c2b-a3b5-4da19b6d3bde", "label": "Other But External URL Link", "type": "uri", "uri": "http://foo.bar", "target": "_blank", "nodes": [] } ] } ] } } } } } }, "/api/v1/documents/{documentId}/addDeliveryStatus": { "post": { "security": [ { "bearerAuth": [ "public-api:write" ] } ], "tags": [ "Add Delivery Status" ], "operationId": "addDeliveryStatusToDocument", "summary": "Add Delivery Status", "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`.", "parameters": [ { "name": "documentId", "in": "path", "description": "Id of the document", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "reportId": "2SG2MAA9RwPn", "publicationId": 524, "deliveryHandle": "web", "status": "success", "message": "Message with html" }, "required": [ "publicationId", "deliveryHandle", "status" ], "properties": { "reportId": { "type": "string", "description": "If provided this will update the record, otherwise it will create a new one with a new reportId" }, "publicationId": { "type": "integer" }, "deliveryHandle": { "type": "string" }, "status": { "type": "string", "description": "One of: “success”, “failed”, “in-progress”", "enum": [ "success", "failed", "in-progress" ] }, "message": { "type": "string", "description": "String or sanitized HTML" } } } } } }, "responses": { "200": { "description": "successful operation" } } } }, "/api/v1/documents/{documentId}/commands": { "patch": { "security": [ { "bearerAuth": [ "public-api:write" ] } ], "tags": [ "Document Command API" ], "operationId": "executeDocumentCommands", "summary": "Execute Commands on Documents. Added in release-2023-11.", "description": "Execute a Document Command based on its `id`. All commands run in a single transaction.", "parameters": [ { "name": "documentId", "in": "path", "description": "Id of the document", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "version": 1, "preconditions": [ { "type": "isPublished", "value": true } ], "commands": [ { "operation": "setMetadataProperty", "propertyName": "title", "value": "updated title", "oldValue": "previous title" }, { "operation": "setEditableDirective", "componentId": "doc-1a2b3c4d5", "directiveName": "headline", "value": "updated headline" }, { "operation": "publish" } ] }, "properties": { "version": { "type": "number" }, "preconditions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } } } }, "commands": { "type": "array", "items": { "type": "object", "properties": { "operation": { "type": "string" } } } } } } } } }, "responses": { "204": { "description": "ok", "content": { "application/json": { "example": { "status": 204 } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "example": { "status": 400, "error": "Bad Request", "error_details": { "commands.0.operation": "value of tag \"operation\" must be in oneOf" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "status": 404, "error": "Not Found", "error_details": { "name": "NotFound", "message": "Document Not Found" } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "example": { "status": 409, "error": "Conflict", "error_details": { "name": "Conflict", "message": "The document you tried to update is outdated", "expectedVersion": 1, "currentVersion": 2 } } } } } } } }, "/api/v1/documents/latestPublications": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Publications" ], "operationId": "getLatestPublications", "summary": "Latest Publications", "description": "This endpoint is the list equivalent of the previous one. The response is an array of objects with 3 possible top-level properties: systemdata, metadata, content", "parameters": [ { "name": "fields", "description": "Filters which (comma separated) properties are included in the response. Defaults to `systemdata,metadata,content` (no renditions).", "schema": { "type": "string", "example": "systemdata,metadata,content" }, "in": "query" }, { "name": "limit", "description": "A limit for how much published documents to retrieve. Defaults to 100. Max. 100.", "schema": { "type": "integer", "minimum": 0, "maximum": 100, "example": 100 }, "in": "query" }, { "name": "offset", "description": "An offset into the query. Useful when getting more than 100 results (pagination)", "schema": { "type": "integer" }, "in": "query" }, { "name": "reverse", "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.", "schema": { "type": "boolean" }, "in": "query" }, { "name": "homepage", "description": "Return only the document labeled as homepage in the current project.", "schema": { "type": "boolean" }, "in": "query" }, { "name": "contentTypes", "description": "Comma separated list of content types to use as filter.", "schema": { "type": "string", "example": "regular" }, "in": "query" }, { "name": "documentTypes", "description": "Comma separated list of document types to use as filter.\nCan be one of `article`, `page`, `data-record`.", "schema": { "type": "string", "example": "article,page,data-record" }, "in": "query" }, { "name": "id", "description": "Filter by one or multiple document ids.\n\nExample 1: `?id=12`\n\nExample 2: `?id=100,120,123` ", "schema": { "type": "string" }, "in": "query" }, { "name": "id.gte", "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&id.lte=100`\n\nRequest 2: `?id.gt=100&id.lte=200`\n\nRequest 3: `?id.gt=200&id.lte=300`", "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" }, "in": "query" }, { "name": "publishedAt.gte", "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&publishedAt.gte=2021-05-01T00:00:00.000Z`", "schema": { "type": "string", "format": "date-time", "example": "2021-01-30T08:30:00Z" }, "in": "query" }, { "name": "publishedAt.gt", "schema": { "type": "string", "format": "date-time", "example": "2021-01-30T08:30:00Z" }, "in": "query" }, { "name": "publishedAt.lte", "schema": { "type": "string", "format": "date-time", "example": "2021-01-30T08:30:00Z" }, "in": "query" }, { "name": "publishedAt.lt", "schema": { "type": "string", "format": "date-time", "example": "2021-01-30T08:30:00Z" }, "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "systemdata": { "$ref": "#/components/schemas/Systemdata" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "content": { "$ref": "#/components/schemas/Content" } } }, "example": [ { "systemdata": { "projectId": 1, "channelId": 1, "documentId": 1, "contentType": "article", "documentType": "article", "publicationId": 1, "firstPublicationDate": "2022-03-16T14:08:11.000Z", "significantPublicationDate": "2022-10-26T07:25:00.000Z", "visiblePublicationDate": "2022-10-27T06:00:00.000Z", "updatedAt": "2022-10-30T16:32:04.170Z", "layout": "regular", "design": { "name": "timeline", "version": "1.1.0" } }, "metadata": { "title": "a title", "description": "some lead", "dependencies": {} }, "content": [ { "id": "doc-1b8i1ksh10", "identifier": "timeline.head", "component": "head", "content": { "title": "a title", "text": "some lead" } }, { "id": "doc-1b8i1ksh20", "identifier": "timeline.normal", "component": "normal", "content": { "caption": "my caption" }, "styles": { "position": "left" } }, { "id": "doc-1b8i1ksh30", "identifier": "timeline.p", "component": "p", "content": { "text": "first paragraph" } }, { "id": "doc-1b8i1me1d0", "identifier": "timeline.p", "component": "p", "content": { "text": "second paragraph" } } ] }, { "systemdata": { "projectId": 1, "channelId": 1, "documentId": 2, "contentType": "article", "documentType": "article", "publicationId": 5, "firstPublicationDate": "2022-03-16T14:08:11.000Z", "significantPublicationDate": "2022-10-26T07:25:00.000Z", "visiblePublicationDate": "2022-10-27T06:00:00.000Z", "updatedAt": "2022-10-30T16:32:04.170Z", "layout": "regular", "design": { "name": "timeline", "version": "1.1.0" } }, "metadata": { "title": "another title", "description": "some other lead", "dependencies": {} }, "content": [ { "id": "doc-1b8i1ksh10", "identifier": "timeline.head", "component": "head", "content": { "title": "a title", "text": "some lead" } }, { "id": "doc-1b8i1ksh20", "identifier": "timeline.normal", "component": "normal", "content": { "caption": "my caption" }, "styles": { "position": "left" } }, { "id": "doc-1b8i1ksh30", "identifier": "timeline.p", "component": "p", "content": { "text": "first paragraph" } }, { "id": "doc-1b8i1me1d0", "identifier": "timeline.p", "component": "p", "content": { "text": "second paragraph" } } ] } ] } } } } } } }, "/api/beta/documents/latestPublications": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Publications" ], "operationId": "getLatestPublicationsBeta", "summary": "Latest Publications Beta", "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", "parameters": [ { "name": "fields", "description": "Filters which (comma separated) properties are included in the response. Defaults to `systemdata,metadata,content` (no renditions).", "schema": { "type": "string", "example": "systemdata,metadata,content,references" }, "in": "query" }, { "name": "limit", "description": "A limit for how much published documents to retrieve. Defaults to 100. Max. 100.", "schema": { "type": "integer", "minimum": 0, "maximum": 100, "example": 100 }, "in": "query" }, { "name": "offset", "description": "An offset into the query. Useful when getting more than 100 results (pagination)", "schema": { "type": "integer" }, "in": "query" }, { "name": "reverse", "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.", "schema": { "type": "boolean" }, "in": "query" }, { "name": "homepage", "description": "Return only the document labeled as homepage in the current project.", "schema": { "type": "boolean" }, "in": "query" }, { "name": "contentTypes", "description": "Comma separated list of content types to use as filter.", "schema": { "type": "string", "example": "regular" }, "in": "query" }, { "name": "documentTypes", "description": "Comma separated list of document types to use as filter.\nCan be one of `article`, `page`, `data-record`.", "schema": { "type": "string", "example": "article,page,data-record" }, "in": "query" }, { "name": "id", "description": "Filter by one or multiple document ids.\n\nExample 1: `?id=12`\n\nExample 2: `?id=100,120,123` ", "schema": { "type": "string" }, "in": "query" }, { "name": "id.gte", "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&id.lte=100\nRequest 2: ?id.gt=100&id.lte=200\nRequest 3: ?id.gt=200&id.lte=300", "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" }, "in": "query" }, { "name": "publishedAt.gte", "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&publishedAt.gte=2021-05-01T00:00:00.000Z`", "schema": { "type": "string", "format": "date-time", "example": "2021-01-30T08:30:00Z" }, "in": "query" }, { "name": "publishedAt.gt", "schema": { "type": "string", "format": "date-time", "example": "2021-01-30T08:30:00Z" }, "in": "query" }, { "name": "publishedAt.lte", "schema": { "type": "string", "format": "date-time", "example": "2021-01-30T08:30:00Z" }, "in": "query" }, { "name": "publishedAt.lt", "schema": { "type": "string", "format": "date-time", "example": "2021-01-30T08:30:00Z" }, "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "systemdata": { "$ref": "#/components/schemas/Systemdata" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "content": { "$ref": "#/components/schemas/Content" }, "renditions": { "$ref": "#/components/schemas/References" } } }, "example": [ { "systemdata": { "projectId": 1, "channelId": 1, "documentId": 1, "contentType": "article", "documentType": "article", "publicationId": 1, "firstPublicationDate": "2022-03-16T14:08:11.000Z", "significantPublicationDate": "2022-10-26T07:25:00.000Z", "visiblePublicationDate": "2022-10-27T06:00:00.000Z", "updatedAt": "2022-10-30T16:32:04.170Z", "layout": "regular", "design": { "name": "timeline", "version": "1.1.0" } }, "metadata": { "title": "a title", "description": "some lead", "dependencies": {} }, "content": [ { "id": "doc-1b8i1ksh10", "identifier": "timeline.head", "component": "head", "content": { "title": "a title", "text": "some lead" } }, { "id": "doc-1b8i1ksh20", "identifier": "timeline.normal", "component": "normal", "content": { "caption": "my caption" }, "styles": { "position": "left" } }, { "id": "doc-1b8i1ksh30", "identifier": "timeline.p", "component": "p", "content": { "text": "first paragraph" } }, { "id": "doc-1b8i1me1d0", "identifier": "timeline.p", "component": "p", "content": { "text": "second paragraph" } } ], "references": [ { "id": "YbzTpusGyJtF", "type": "language-group", "location": "metadata", "propertyName": "language" } ] }, { "systemdata": { "projectId": 1, "channelId": 1, "documentId": 2, "contentType": "article", "documentType": "article", "publicationId": 5, "firstPublicationDate": "2022-03-16T14:08:11.000Z", "significantPublicationDate": "2022-10-26T07:25:00.000Z", "visiblePublicationDate": "2022-10-27T06:00:00.000Z", "updatedAt": "2022-10-30T16:32:04.170Z", "layout": "regular", "design": { "name": "timeline", "version": "1.1.0" } }, "metadata": { "title": "another title", "description": "some other lead", "dependencies": {} }, "content": [ { "id": "doc-1b8i1ksh10", "identifier": "timeline.head", "component": "head", "content": { "title": "a title", "text": "some lead" } }, { "id": "doc-1b8i1ksh20", "identifier": "timeline.normal", "component": "normal", "content": { "caption": "my caption" }, "styles": { "position": "left" } }, { "id": "doc-1b8i1ksh30", "identifier": "timeline.p", "component": "p", "content": { "text": "first paragraph" } }, { "id": "doc-1b8i1me1d0", "identifier": "timeline.p", "component": "p", "content": { "text": "second paragraph" } } ], "references": [ { "id": "YbzTpusGyJtF", "type": "language-group", "location": "metadata", "propertyName": "language" } ] } ] } } } } } } }, "/api/v1/documents/{documentId}/latestPublication": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Publications" ], "operationId": "getLatestPublicationForDocument", "summary": "Latest Publication", "description": "Required scope: public-api:read. The response is a JSON object with 4 possible top-level properties: systemdata, metadata, content, renditions", "parameters": [ { "name": "documentId", "schema": { "type": "integer" }, "in": "path", "required": true }, { "name": "fields", "description": "Filters which (comma separated) properties are included in the response. Defaults to `systemdata,metadata,content,renditions`.", "schema": { "type": "string", "example": "systemdata,metadata,content,renditions" }, "in": "query" }, { "name": "renditions", "description": "A comma-separated list of rendition handles. Example: ?renditions=web,json", "schema": { "type": "string", "example": "web,json" }, "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LatestPublicationForDocumentResponse" } } } } } } }, "/api/beta/documents/{documentId}/latestPublication": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Publications" ], "operationId": "getLatestPublicationForDocumentBeta", "summary": "Latest Publication Beta", "description": "The response is a JSON object with 5 possible top-level properties: systemdata, metadata, content, renditions, references", "parameters": [ { "name": "documentId", "schema": { "type": "integer" }, "in": "path", "required": true }, { "name": "fields", "description": "Filters which (comma separated) properties are included in the response.", "schema": { "type": "string", "example": "systemdata,metadata,content,renditions,references," }, "in": "query" }, { "name": "renditions", "description": "A comma-separated list of rendition handles. Example: ?renditions=web,json", "schema": { "type": "string", "example": "web,json" }, "in": "query" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "systemdata": { "$ref": "#/components/schemas/Systemdata" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "content": { "$ref": "#/components/schemas/Content" }, "renditions": { "$ref": "#/components/schemas/Renditions" }, "references": { "$ref": "#/components/schemas/References" } }, "example": { "systemdata": { "projectId": 1, "channelId": 1, "documentId": 1, "contentType": "article", "documentType": "article", "publicationId": 1, "firstPublicationDate": "2022-03-16T14:08:11.000Z", "significantPublicationDate": "2022-10-26T07:25:00.000Z", "visiblePublicationDate": "2022-10-27T06:00:00.000Z", "updatedAt": "2023-03-18T16:32:04.170Z", "layout": "regular", "design": { "name": "timeline", "version": "1.1.0" } }, "metadata": { "title": "a title", "description": "some lead", "dependencies": {} }, "content": [ { "id": "doc-1b8i1ksh10", "identifier": "timeline.head", "component": "head", "content": { "title": "a title", "text": "some lead" } }, { "id": "doc-1b8i1ksh20", "identifier": "timeline.normal", "component": "normal", "content": { "caption": "my caption" }, "styles": { "position": "left" } }, { "id": "doc-1b8i1ksh30", "identifier": "timeline.p", "component": "p", "content": { "text": "first paragraph" } }, { "id": "doc-1b8i1me1d0", "identifier": "timeline.p", "component": "p", "content": { "text": "second paragraph" } } ], "renditions": [ { "handle": "web", "content": "
\n

a title

\n

some lead

\n
\n
\n \n
my caption
\n
\n

first paragraph

\n

second

\n

and third one. :)

" }, { "handle": "mobile", "content": { "content": [ { "id": "doc-1b8i1ksh10", "identifier": "timeline.head", "component": "head", "content": { "title": "a title", "text": "some lead" } }, { "id": "doc-1b8i1ksh20", "identifier": "timeline.normal", "component": "normal", "content": { "caption": "my caption" }, "styles": { "position": "left" } }, { "id": "doc-1b8i1ksh30", "identifier": "timeline.p", "component": "p", "content": { "text": "first paragraph" } }, { "id": "doc-1b8i1me1d0", "identifier": "timeline.p", "component": "p", "content": { "text": "second paragraph" } } ], "design": { "name": "timeline", "version": "1.1.0" } } }, { "handle": "app", "error": { "message": "Processing of Channel 'app' for document '1' failed. Detailed error message…" } } ], "references": [ { "id": "YbzTpusGyJtF", "type": "language-group", "location": "metadata", "propertyName": "language" } ] } } } } } } } }, "/api/v1/publicationEvents": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Publications" ], "operationId": "getPublicationEvents", "summary": "Publication Events", "description": "Get Publication Events for the default channel", "parameters": [ { "name": "limit", "description": "Number of events to return. Default: 100. Highest limit: 1000.", "schema": { "type": "integer", "example": 100 }, "in": "query" }, { "name": "reverse", "description": "Returns the events in reverse order, starting at the biggest id.", "schema": { "type": "boolean", "example": false }, "in": "query" }, { "name": "contentTypes", "description": "Comma separated list of content types to use as filter.", "schema": { "type": "string" }, "in": "query" }, { "name": "documentTypes", "description": "Comma separated list of document types to use as filter. \n\nCan be one of `article`, `page`, `data-record`.", "schema": { "type": "string" }, "in": "query" }, { "name": "after", "description": "**Deprecated**: Please use `id.gte` instead.\n\nReturn matching events after this event id.", "schema": { "type": "integer" }, "in": "query", "deprecated": true }, { "name": "id.gte", "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&id.gt=40000`", "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" }, "in": "query" }, { "name": "createdAt.gte", "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&createdAt.gte=2021-05-01T00:00:00.000Z`", "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" }, "in": "query" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" }, "example": [ { "id": 910, "createdAt": "2016-12-27T09:19:00.928Z", "projectId": 30, "channelId": 53, "documentId": 7892, "documentType": "article", "eventType": "publish", "publicationId": 1066 }, { "id": 988, "createdAt": "2016-12-27T09:32:10.898Z", "projectId": 30, "channelId": 53, "documentId": 7892, "documentType": "article", "eventType": "unpublish", "publicationId": 1100 }, { "id": 990, "createdAt": "2016-12-27T09:33:05.010Z", "projectId": 30, "channelId": 53, "documentId": 8005, "documentType": "article", "eventType": "publish", "publicationId": 1131 }, { "id": 1011, "createdAt": "2016-12-27T09:33:31.517Z", "projectId": 30, "channelId": 53, "documentId": 7892, "documentType": "article", "eventType": "update", "publicationId": 1394 } ] } } } } } } }, "/api/v1/publicationEvents/{channelHandle}": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Publications" ], "operationId": "getPublicationEventsForChannel", "summary": "Publication Events by Channel", "description": "Get Publication Events", "parameters": [ { "name": "channelHandle", "description": "The handle of the channel for which you want to get the events.", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "limit", "description": "Number of events to return. Default: 100. Highest limit: 1000.", "schema": { "type": "integer", "example": 100 }, "in": "query" }, { "name": "reverse", "description": "Returns the events in reverse order, starting at the biggest id.", "schema": { "type": "boolean", "example": false }, "in": "query" }, { "name": "contentTypes", "description": "Comma separated list of content types to use as filter.", "schema": { "type": "string" }, "in": "query" }, { "name": "documentTypes", "description": "Comma separated list of document types to use as filter. \n\nCan be one of `article`, `page`, `data-record`.", "schema": { "type": "string" }, "in": "query" }, { "name": "after", "description": "**Deprecated**: Please use `id.gte` instead.\n\nReturn matching events after this event id.", "schema": { "type": "integer" }, "in": "query", "deprecated": true }, { "name": "id.gte", "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&id.gt=40000`", "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" }, "in": "query" }, { "name": "createdAt.gte", "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&createdAt.gte=2021-05-01T00:00:00.000Z`", "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" }, "in": "query" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" }, "example": [ { "id": 910, "createdAt": "2016-12-27T09:19:00.928Z", "projectId": 30, "channelId": 53, "documentId": 7892, "documentType": "article", "eventType": "publish", "publicationId": 1066 }, { "id": 988, "createdAt": "2016-12-27T09:32:10.898Z", "projectId": 30, "channelId": 53, "documentId": 7892, "documentType": "article", "eventType": "unpublish", "publicationId": 1100 }, { "id": 990, "createdAt": "2016-12-27T09:33:05.010Z", "projectId": 30, "channelId": 53, "documentId": 8005, "documentType": "article", "eventType": "publish", "publicationId": 1131 }, { "id": 1011, "createdAt": "2016-12-27T09:33:31.517Z", "projectId": 30, "channelId": 53, "documentId": 7892, "documentType": "article", "eventType": "update", "publicationId": 1394 } ] } } } } } } }, "/api/v1/documents/{documentId}/incomingDocumentReferences": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Publications" ], "operationId": "getIncomingDocumentReferencesForDocument", "summary": "Incoming Publication References", "description": "Get Incoming Publication References for a Document", "parameters": [ { "name": "documentId", "schema": { "type": "integer" }, "in": "path", "required": true }, { "name": "limit", "description": "A limit for how much published documents to retrieve. Defaults to 100. Max. 100.", "schema": { "type": "integer", "example": 100 }, "in": "query" }, { "name": "offset", "description": "An offset into the query. Useful when getting more than 100 results (pagination).", "schema": { "type": "integer", "example": 0 }, "in": "query" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" }, "example": [ { "id": 4, "references": [ { "id": "1", "type": "document", "location": "include-directive", "componentId": "doc-1euiflvoq0", "serviceName": "editable-teaser", "propertyName": "article", "componentName": "teaser-include", "directiveName": "teaser" } ] }, { "id": 2, "references": [ { "id": "1", "type": "document", "location": "include-directive", "componentId": "doc-1eu6i7l880", "serviceName": "editable-teaser", "propertyName": "article", "componentName": "teaser-include", "directiveName": "teaser" } ] } ] } } } } } } }, "/api/v1/documents/{documentId}/incomingMediaReferences": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Publications" ], "operationId": "getIncomingMediaReferencesForDocument", "summary": "Incoming Media References", "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/)", "parameters": [ { "name": "documentId", "schema": { "type": "integer" }, "in": "path", "required": true }, { "name": "limit", "description": "A limit for how much published documents to retrieve. Defaults to 100. Max. 100.", "schema": { "type": "integer", "example": 100 }, "in": "query" }, { "name": "offset", "description": "An offset into the query. Useful when getting more than 100 results (pagination).", "schema": { "type": "integer", "example": 0 }, "in": "query" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" }, "example": [ { "id": "98sXCahM5PEk", "references": [ { "id": "3", "type": "document", "location": "metadata", "propertyName": "documentLink" } ] } ] } } } } } } }, "/api/v1/documents/{documentId}/latestPublication/renditions/{renditionHandles}": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Publications" ], "operationId": "getDocumentRendition", "summary": "Get Specific Renditions for a Publication", "description": "**Upcoming Deprecation**\n\nPlease note that we’re working on offering a better alternative to the renditions with the `Composition API`.\n\nIf you need the HTML for a document you can use the `Composition API` and pass the field `html`.\n\n**Required Server Configuration**\n\nRenditions are only available if configured in the contentType configuration.", "parameters": [ { "name": "renditionHandles", "description": "A comma-separated list of renditions handles, e.g. `web,name`.", "schema": { "type": "string" }, "in": "path", "required": true, "example": "web,name" }, { "name": "documentId", "schema": { "type": "integer" }, "in": "path", "required": true } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" }, "example": [ { "handle": "web", "content": "
\n

a title

\n

some lead

\n
\n
\n \n
my caption
\n
\n

first paragraph

\n

second

\n

and third one. :)

" }, { "handle": "mobile", "content": [ { "id": "doc-1b8i1ksh10", "identifier": "timeline.head", "component": "head", "content": { "title": "a title", "text": "some lead" } }, { "id": "doc-1b8i1ksh20", "identifier": "timeline.normal", "component": "normal", "content": { "caption": "my caption" }, "styles": { "position": "left" } }, { "id": "doc-1b8i1ksh30", "identifier": "timeline.p", "component": "p", "content": { "text": "first paragraph" } }, { "id": "doc-1b8i1me1d0", "identifier": "timeline.p", "component": "p", "content": { "text": "second paragraph" } } ], "design": { "name": "timeline", "version": "1.1.0" } }, { "handle": "app", "error": { "message": "Processing of Channel 'app' for document '1' failed. Detailed error message…" } } ] } } } } } } }, "/api/beta/documents/{documentId}/latestDraft": { "get": { "security": [ { "bearerAuth": [ "public-api:write", "public-api:drafts:read" ] } ], "tags": [ "Drafts" ], "operationId": "getLatestDraftForDocument", "summary": "Get Latest Draft", "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 \n- renditions (if rendition handles are specified)", "parameters": [ { "name": "documentId", "schema": { "type": "integer" }, "in": "path", "required": true }, { "name": "renditions", "description": "A comma-separated list of rendition handles. Example: `?renditions=web,json`", "schema": { "type": "string", "example": "web,json" }, "in": "query" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "example": { "systemdata": { "projectId": 1, "channelId": 1, "documentId": 603, "contentType": "regular", "documentType": "article", "firstPublicationDate": "2022-02-22T16:33:42.836Z", "updatedAt": "2022-02-22T16:33:42.836Z", "design": { "name": "living-times", "version": "1.0.4" } }, "content": [ { "id": "doc-1fsh4faeo0", "identifier": "living-times.article-container", "component": "article-container", "position": "fixed", "containers": { "main": [ { "id": "doc-1fsh4faeo3", "identifier": "living-times.paragraph", "component": "paragraph", "content": { "text": "First paragraph published." } }, { "id": "doc-1fsh4g83l0", "identifier": "living-times.paragraph", "component": "paragraph", "content": { "text": "Second paragraph unpublished." } } ] } } ], "references": [ { "id": "KjqXSj2P1-L0", "type": "language-group", "location": "metadata", "propertyName": "language" } ], "metadata": { "language": { "label": "German", "locale": "de", "groupId": "KjqXSj2P1-L0" }, "title": "Draft (Changed)" }, "renditions": [ { "handle": "web", "content": "
\n

a title

\n

some lead

\n
\n
\n \n
my caption
\n
\n

first paragraph

\n

second

\n

and third one. :)

" } ] } } } } } } } }, "/api/v1/drafts/{documentId}/incomingDocumentReferences": { "get": { "security": [ { "bearerAuth": [ "public-api:drafts:read" ] } ], "tags": [ "Drafts" ], "operationId": "getIncomingDraftReferences", "summary": "Get Incoming Draft References for a Document", "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.", "parameters": [ { "name": "documentId", "schema": { "type": "integer" }, "in": "path", "required": true }, { "name": "limit", "description": "A limit for how much documents to retrieve. Defaults to 100. Max. 100.", "schema": { "type": "integer", "example": 100 }, "in": "query" }, { "name": "offset", "description": "An offset into the query. Useful when getting more than 100 results (pagination).", "schema": { "type": "integer", "example": 0 }, "in": "query" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "array", "example": [ { "id": 4, "references": [ { "id": "1", "type": "document", "location": "include-directive", "componentId": "doc-1euiflvoq0", "serviceName": "editable-teaser", "propertyName": "article", "componentName": "teaser-include", "directiveName": "teaser" } ] }, { "id": 2, "references": [ { "id": "1", "type": "document", "location": "include-directive", "componentId": "doc-1eu6i7l880", "serviceName": "editable-teaser", "propertyName": "article", "componentName": "teaser-include", "directiveName": "teaser" } ] } ] } } } } } } }, "/api/v1/import/documents": { "post": { "security": [ { "bearerAuth": [ "public-api:write" ] } ], "tags": [ "Imports" ], "operationId": "getImportDocuments", "summary": "Import Documents", "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.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "systemName": "identifier-for-your-system", "webhook": "https://my-domain.com/webhooks/document-import", "context": { "myIdentifier": "some-identifier-sent-to-the-webhook" }, "documents": [ { "id": "123abc", "title": "test import", "contentType": "article", "checksum": "xyz456", "publicationDate": "1999-03-18T17:27:00.107Z", "livingdoc": { "content": [ { "identifier": "header", "content": { "catchline": "imported catchline", "title": "imported title", "author": "imported author" } } ], "design": { "name": "living-times", "version": "1.0.1" } }, "metadata": { "description": "foo" }, "translations": [ { "locale": "fr", "metadata": { "description": "foo FR" } } ], "flags": { "autoPublish": true } } ] }, "required": [ "systemName", "documents" ], "properties": { "systemName": { "type": "string", "description": "Identifier for the system you are importing from, e.g. an archive" }, "webhook": { "type": "string", "format": "uri", "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." }, "context": { "type": "object", "description": "An object that is passed as context in the body of the request to the webhook. Limited to 8192 Bytes." }, "documents": { "description": "An array of documents to import. Each entry is an object.", "type": "array", "items": { "type": "object", "required": [ "id", "checksum", "title", "contentType", "publicationDate", "livingdoc", "metadata" ], "properties": { "id": { "type": "string", "description": "a unique id (stored as externalId in Livingdocs) that identifies the document on your end, must be unique within your project." }, "title": { "type": "string", "description": "the title that the document should get in livingdocs" }, "checksum": { "type": "string", "description": "string to identify changes, e.g. an updated_at timestamp" }, "contentType": { "type": "string", "description": "the content type that the document should get in livingdocs" }, "publicationDate": { "type": "string", "format": "date-time", "description": "sets the date of a publication. `autoPublish’ flag must be set for this to have an effect." }, "livingdoc": { "type": "object", "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." }, "metadata": { "type": "object", "description": "An object of metadata, must conform to your channel-config otherwise throws a validation error" }, "translations": { "type": "array", "items": { "type": "object" }, "description": "sets the date of a publication. `autoPublish` flag must be set for this to have an effect." }, "flags": { "type": "object", "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" } } } } } } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "example": { "id": "25bzj8j" } } } } }, "429": { "description": "Usage Limit Exceeded", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" }, "example": [ { "status": 429, "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." } } ] } } } } } } }, "/api/v1/import/documents/status": { "get": { "security": [ { "bearerAuth": [ "public-api:write" ] } ], "tags": [ "Imports" ], "operationId": "getDocumentImportStatus", "summary": "Check Import Status for Documents", "description": "You can use this endpoint to check for the status and/or result of a document import.", "parameters": [ { "name": "id", "schema": { "type": "string" }, "required": true, "in": "query" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "example": { "finished": true, "state": "success", "id": "25bzj8j", "logs": [ { "system_name": "integration-tests", "external_id": "8Sv9Nu0d", "document_id": 1, "checksum": "123abc", "project_id": 3, "channel_id": 2, "revision_id": 1, "version": 1, "id": 1, "state": "imported" }, { "state": "failed", "reason": "Invalid metadata", "external_id": "external-unique-id-345", "title": "my second document" } ] } } } } } } } }, "/api/v1/import/images": { "post": { "security": [ { "bearerAuth": [ "public-api:write" ] } ], "tags": [ "Imports" ], "operationId": "importImage", "summary": "Import Images", "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.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "systemName": "identifier-for-your-system", "webhook": "https://my-domain.com/webhooks/image-import", "context": { "myIdentifier": "some-identifier-sent-to-the-webhook" }, "images": [ { "url": "https://placekitten.com/800/600", "id": "123abc", "fileName": "cat", "mediaType": "image", "metadata": { "title": "kitten" } } ] }, "required": [ "systemName", "images" ], "properties": { "systemName": { "type": "string", "description": "Identifier for the system you are importing from, e.g. an archive" }, "webhook": { "type": "string", "format": "uri", "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." }, "context": { "type": "object", "description": "An object that is passed as context in the body of the request to the webhook. Limited to 8192 Bytes." }, "images": { "description": "An array of images to import. Each entry is an object with the following keys, all of which are required:", "type": "array", "items": { "type": "object", "required": [ "id", "url", "fileName", "metadata", "mediaType" ], "properties": { "id": { "type": "string", "description": "a unique id (stored as externalId in Livingdocs) that identifies the document on your end, must be unique within your project." }, "url": { "type": "string", "format": "uri", "description": "a URL to an image file, no data urls allowed, must be an image, allowed types: png, jpg, gif, svg" }, "fileName": { "type": "string", "description": "the title that the image should get in livingdocs" }, "metadata": { "type": "object", "description": "An object of metadata according to your project config" }, "mediaType": { "type": "string", "description": "the handle of one of the mediaTypes from your project configuration" } } } } } } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "example": { "id": "25bzj8j" } } } } }, "429": { "description": "Usage Limit Exceeded", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" }, "example": [ { "status": 429, "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." } } ] } } } } } } }, "/api/v1/import/images/status": { "get": { "security": [ { "bearerAuth": [ "public-api:write" ] } ], "tags": [ "Imports" ], "operationId": "getImageImportStatus", "summary": "Check Import Status for Images", "description": "You can use this endpoint to check for the status and/or result of a image import.", "parameters": [ { "name": "id", "description": "The id that Livingdocs provided you for your prior call to `/import/images`", "schema": { "type": "string" }, "required": true, "in": "query" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "example": { "finished": true, "state": "success", "id": "25bzj8j", "images": [ { "status": "success", "externalId": "external-unique-id-123", "title": "my image", "image": { "mediaId": "jjiwhsf23kdk", "originalUrl": "https://server.livingdocs.io/api/v1/images/truck-in-flood-water?id=MQkvMjAxOS8xMS8yMS9hMjA5NzkwZS0xNTQ5LTQ2ZDktYjNjNy1jZWZlMjhjN2VhOTkuanBlZwk2NzM=", "url": "https://server.livingdocs.io/api/v1/images/truck-in-flood-water?id=MQkvMjAxOS8xMS8yMS9hMjA5NzkwZS0xNTQ5LTQ2ZDktYjNjNy1jZWZlMjhjN2VhOTkuanBlZwk2NzM=?format=auto", "width": 100, "height": 100, "mimeType": "image/png", "imageService": "imgix" } }, { "status": "skipped", "reason": "already exists", "externalId": "external-unique-id-234", "title": "my second image", "image": { "mediaId": "jjiwhsf23wer", "originalUrl": "https://server.livingdocs.io/api/v1/images/truck-in-flood-water?id=MQkvMjAxOS8xMS8yMS9hMjA5NzkwZS0xNTQ5LTQ2ZDktYjNjNy1jZWZlMjhjN2VhOTkuanBlZwk2NzM=", "url": "https://server.livingdocs.io/api/v1/images/truck-in-flood-water?id=MQkvMjAxOS8xMS8yMS9hMjA5NzkwZS0xNTQ5LTQ2ZDktYjNjNy1jZWZlMjhjN2VhOTkuanBlZwk2NzM=?format=auto", "width": 100, "height": 100, "mimeType": "image/png", "imageService": "imgix" } }, { "status": "failed", "reason": "Could not upload image", "externalId": "external-unique-id-345", "title": "my third image" } ] } } } } } } } }, "/api/v1/import/videos": { "post": { "security": [ { "bearerAuth": [ "public-api:write" ] } ], "tags": [ "Imports" ], "operationId": "importVideos", "summary": "Import Videos", "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.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "systemName": "identifier-for-your-system", "webhook": "https://my-domain.com/webhooks/video-import", "context": { "myIdentifier": "some-identifier-sent-to-the-webhook" }, "videos": [ { "url": "https://www.learningcontainer.com/wp-content/uploads/2020/05/sample-mp4-file.mp4", "id": "123abc", "fileName": "foo", "metadata": { "title": "sample video", "credit": "LC" } } ] }, "required": [ "systemName", "videos" ], "properties": { "systemName": { "type": "string", "description": "Identifier for the system you are importing from, e.g. an archive" }, "webhook": { "type": "string", "format": "uri", "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." }, "context": { "type": "object", "description": "An object that is passed as context in the body of the request to the webhook. Limited to 8192 Bytes." }, "videos": { "description": "An array of videos to import. Each entry is an object with the following keys, all of which are required:", "type": "array", "items": { "type": "object", "required": [ "id", "url", "fileName", "metadata" ], "properties": { "id": { "type": "string", "description": "a unique id (stored as externalId in Livingdocs) that identifies the document on your end, must be unique within your project." }, "url": { "type": "string", "format": "uri", "description": "a URL to an video file, no data urls allowed, must be an video, allowed types: (TODO)" }, "fileName": { "type": "string", "description": "the title that the video should get in livingdocs" }, "metadata": { "type": "object", "description": "An object of metadata according to your project config" } } } } } } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "example": { "id": "25bzj8j" } } } } }, "429": { "description": "Usage Limit Exceeded", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" }, "example": [ { "status": 429, "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." } } ] } } } } } } }, "/api/v1/import/mediaLibrary": { "post": { "security": [ { "bearerAuth": [ "public-api:write" ] } ], "tags": [ "Imports" ], "operationId": "importMediaLibraryEntries", "summary": "Import Media Library Entries", "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.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "mediaLibraryEntries": [ { "id": "custom-1", "systemName": "externalSystem", "externalId": "6hedie82", "mediaType": "image", "asset": { "key": "2022/08/25/d6068c02-ca85-421d-948d-ee0e2c15f372.jpeg", "url": "https://livingdocs-images-development.s3.amazonaws.com/2022/08/25/d6068c02-ca85-421d-948d-ee0e2c15f372.jpeg", "size": 34910, "width": 640, "height": 427, "filename": "super-mario.jpeg", "mimeType": "image/jpeg" }, "metadata": { "title": "This is Super Mario!" }, "translations": [ { "asset": { "key": "2022/09/30/60984f90-c766-4546-9bc8-61f0832f9755.jpeg", "url": "https://livingdocs-images-development.s3.amazonaws.com/2022/09/30/60984f90-c766-4546-9bc8-61f0832f9755.jpeg", "size": 188497, "width": 640, "height": 853, "filename": "jpg-super-mario-wall.jpg", "mimeType": "image/jpeg" }, "locale": "fr", "metadata": { "title": "C'est Super Mario!" } } ] }, { "id": "custom-2", "systemName": "externalSystem", "externalId": "ahedie8x", "mediaType": "file", "asset": { "key": "2022/09/30/a1cb173d-e85f-498b-996e-5ce46058e9b9.pdf", "url": "https://livingdocs-files-development.s3.amazonaws.com/2022/09/30/a1cb173d-e85f-498b-996e-5ce46058e9b9.pdf", "size": 3028, "filename": "a-simple-pdf.pdf", "mimeType": "application/pdf" }, "metadata": { "title": "A simple PDF" }, "translations": [ { "locale": "fr", "metadata": { "title": "Un simple PDF" } } ] }, { "id": "custom-3", "systemName": "externalSystem", "externalId": "srfhediess", "mediaType": "video", "asset": { "key": "2022/09/30/2804fc3d-098d-4f8f-b25c-c6c15583d672.mp4", "url": "https://livingdocs-videos-development.s3.amazonaws.com/2022/09/30/2804fc3d-098d-4f8f-b25c-c6c15583d672.mp4", "size": 8633462, "width": 1280, "height": 720, "duration": 35.241667, "filename": "fire.mp4", "mimeType": "video/mp4" }, "metadata": { "title": "This is a fire" }, "translations": [ { "locale": "fr", "metadata": { "title": "C'est un feu" } } ] } ] }, "required": [ "mediaLibraryEntries" ], "properties": { "mediaLibraryEntries": { "description": "An array of documents to import. Each entry is an object.", "type": "array", "items": { "type": "object", "discriminator": { "propertyName": "mediaType" }, "properties": { "mediaType": { "type": "string" } }, "required": [ "mediaType" ], "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9\\-]{1,32}$", "description": "Custom id (Allowed characters: a-z, A-Z, 0-9, and -). If omitted a random id will be generated." }, "systemName": { "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." }, "externalId": { "type": "string", "description": "Must be unique in combination with systemName." }, "mediaType": { "type": "string", "enum": [ "image" ] }, "asset": { "type": "object", "properties": { "key": { "type": "string" }, "url": { "type": "string", "format": "uri", "pattern": "(http)?s?:?(\\/\\/[^\"']*\\.(?:png|jpg|jpeg|gif|png|svg|webp|mp4|mov))" }, "size": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "filename": { "type": "string" }, "mimeType": { "type": "string" } }, "required": [ "key", "url", "size", "width", "height", "mimeType", "filename" ] }, "metadata": { "type": "object" }, "translations": { "$ref": "#/components/schemas/MediaLibraryTranslations" } }, "required": [ "mediaType", "asset" ] }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9\\-]{1,32}$", "description": "Custom id (Allowed characters: a-z, A-Z, 0-9, and -). If omitted a random id will be generated." }, "systemName": { "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." }, "externalId": { "type": "string", "description": "Must be unique in combination with systemName." }, "mediaType": { "type": "string", "enum": [ "file" ] }, "asset": { "type": "object", "properties": { "key": { "type": "string" }, "url": { "type": "string", "format": "uri", "pattern": "(http)?s?:?(\\/\\/[^\"']*\\.*)" }, "size": { "type": "number" }, "filename": { "type": "string" }, "mimeType": { "type": "string" } }, "required": [ "key", "url", "size", "mimeType", "filename" ] }, "metadata": { "type": "object" }, "translations": { "$ref": "#/components/schemas/MediaLibraryTranslations" } }, "required": [ "mediaType", "asset" ] }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9\\-]{1,32}$", "description": "Custom id (Allowed characters: a-z, A-Z, 0-9, and -). If omitted a random id will be generated." }, "systemName": { "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." }, "externalId": { "type": "string", "description": "Must be unique in combination with systemName." }, "mediaType": { "type": "string", "enum": [ "video" ] }, "asset": { "type": "object", "properties": { "key": { "type": "string" }, "url": { "type": "string", "format": "uri", "pattern": "(http)?s?:?(\\/\\/[^\"']*\\.*)" }, "size": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "duration": { "type": "number" }, "filename": { "type": "string" }, "mimeType": { "type": "string" } }, "required": [ "key", "url", "size", "width", "height", "duration", "mimeType", "filename" ] }, "metadata": { "type": "object" }, "translations": { "$ref": "#/components/schemas/MediaLibraryTranslations" } }, "required": [ "mediaType", "asset" ] } ] } } } } } } }, "responses": { "200": { "description": "successful operation" } } } }, "/api/v1/sitemaps/index": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Sitemaps" ], "operationId": "getSitemapIndex", "summary": "Get a Sitemap's Index", "description": "Get a Sitemap's Index", "parameters": [ { "name": "baseUrl", "description": "Base url of the delivery host", "schema": { "type": "string" }, "in": "query", "required": true }, { "name": "contentTypes", "description": "A comma-separated list of contentTypes to include in the sitemap. Example: `?contentTypes=regular,pages`", "schema": { "type": "string" }, "in": "query", "example": "regular,pages" }, { "name": "entriesPerPage", "description": "Optional sitemap entry page size. Default 20000", "schema": { "type": "string" }, "in": "query", "example": "20000" } ], "responses": { "200": { "description": "Sitemap", "content": { "application/xml": { "examples": { "xml": { "summary": "Sitemap example", "externalValue": "https://livingdocsio.github.io/openapi/examples/sitemap-index.xml" } } } } } } } }, "/api/v1/sitemaps/entries": { "get": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Sitemaps" ], "operationId": "getSitemapEntries", "summary": "Get a Sitemap's Entries", "description": "Get a Sitemap's Entries", "parameters": [ { "name": "baseUrl", "description": "Base url of the delivery host. `?baseUrl=https://livingdocs.io/`", "required": true, "in": "query", "schema": { "type": "string" }, "example": "https://livingdocs.io/" }, { "name": "date", "description": "Date for the specific month matching the schema from the sitemap index file. Example: `?date=2021-06` or `?date=2021-06.2`", "schema": { "type": "string" }, "in": "query", "required": true }, { "name": "contentTypes", "description": "A comma-separated list of contentTypes to include in the sitemap. Example: `?contentTypes=regular,pages`", "schema": { "type": "string" }, "in": "query", "example": "regular,pages" }, { "name": "entriesPerPage", "description": "Optional sitemap entry page size. Default 20000", "schema": { "type": "string" }, "in": "query", "example": "20000" } ], "responses": { "200": { "description": "Sitemap", "content": { "application/xml": { "examples": { "xml": { "summary": "Sitemap example", "externalValue": "https://livingdocsio.github.io/openapi/examples/sitemap-entries.xml" } } } } } } } }, "/api/v1/health": { "get": { "tags": [ "Health" ], "operationId": "getApiStatus", "summary": "Check API Status", "description": "Check API Status", "responses": { "200": { "description": "Status ok" } } } }, "/api/v1/retresco/re-enrich": { "post": { "security": [ { "bearerAuth": [ "retresco" ] } ], "tags": [ "Retresco" ], "operationId": "retrescoReenrich", "summary": "Retresco re-enrich Webhook", "description": "This hook should be used on Retresco when enabling the re-enrich feature to trigger asynchronous document enrichment.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "doc_ids": [ 1, 2, 3, 4 ] }, "required": [ "doc_ids" ], "properties": { "doc_ids": { "type": "array", "items": { "oneOf": [ { "type": "number" }, { "type": "string" } ] } } } } } } }, "responses": { "200": { "description": "doc_ids list accepted to process" } } } }, "/api/beta/composition/{documentId}": { "post": { "security": [ { "bearerAuth": [ "public-api:read" ] } ], "tags": [ "Composition" ], "operationId": "composePublication", "summary": "Compose a publication", "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.", "parameters": [ { "name": "documentId", "schema": { "type": "integer" }, "in": "path", "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompositionApiRequestBody" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompositionApiResponse" } } } } } } } }, "externalDocs": { "description": "Find out more about Livingdocs", "url": "http://docs.livingdocs.io" }, "servers": [ { "url": "http://localhost:9090", "description": "localhost" }, { "url": "{protocol}://{hostname}", "description": "downstream", "variables": { "protocol": { "enum": [ "http", "https" ], "default": "https" }, "hostname": { "default": "example.com" } } }, { "url": "https://server.livingdocs.io", "description": "demo" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "Systemdata": { "type": "object", "properties": { "projectId": { "type": "number" }, "channelId": { "type": "number" }, "documentId": { "type": "number" }, "contentType": { "type": "string" }, "documentType": { "type": "string" }, "publicationId": { "type": "number" }, "firstPublicationDate": { "type": "string", "format": "date-time" }, "significantPublicationDate": { "type": "string", "format": "date-time" }, "visiblePublicationDate": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "layout": { "type": "string" }, "design": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" } } } } }, "Metadata": { "type": "object" }, "Content": { "type": "array", "items": { "type": "object" } }, "ErrorResponse": { "type": "object", "properties": { "status": { "type": "number" }, "error": { "type": "string" }, "error_details": { "type": "object", "properties": { "message": { "type": "string" } } } } }, "Renditions": { "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string" }, "content": { "oneOf": [ { "type": "string", "format": "html" }, { "type": "object" } ] } } } }, "References": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "location": { "type": "string" }, "propertyName": { "type": "string" } } } }, "MediaLibraryEntryAsset": { "type": "object", "additionalProperties": false, "properties": { "storage": { "deprecated": true, "type": "string" }, "key": { "type": "string" }, "url": { "type": "string", "format": "url" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "size": { "type": "integer" }, "duration": { "type": "number" }, "mimeType": { "type": "string" }, "filename": { "type": "string" } } }, "MediaLibraryEntry": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "version": { "type": "number" }, "mediaType": { "type": "string" }, "asset": { "$ref": "#/components/schemas/MediaLibraryEntryAsset" }, "metadata": { "type": "object" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "MediaLibraryTranslations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "locale", "metadata" ], "properties": { "locale": { "type": "string", "pattern": "^[a-z][a-zA-Z0-9\\-]+$" }, "metadata": { "title": "Metadata", "type": "object", "additionalProperties": true }, "asset": { "$ref": "#/components/schemas/MediaLibraryEntryAsset" } } } }, "LatestPublicationForDocumentResponse": { "type": "object", "properties": { "systemdata": { "$ref": "#/components/schemas/Systemdata" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "content": { "$ref": "#/components/schemas/Content" }, "renditions": { "$ref": "#/components/schemas/Renditions" } }, "example": { "systemdata": { "projectId": 1, "channelId": 1, "documentId": 1, "contentType": "regular", "documentType": "article", "publicationId": 1, "firstPublicationDate": "2022-03-16T14:08:11.000Z", "significantPublicationDate": "2022-10-26T07:25:00.000Z", "visiblePublicationDate": "2022-10-27T06:00:00.000Z", "updatedAt": "2023-03-18T16:32:04.170Z", "layout": "regular", "design": { "name": "timeline", "version": "1.1.0" } }, "metadata": { "title": "a title", "description": "some lead", "dependencies": {} }, "content": [ { "id": "doc-1b8i1ksh10", "identifier": "timeline.head", "component": "head", "content": { "title": "a title", "text": "some lead" } }, { "id": "doc-1b8i1ksh20", "identifier": "timeline.normal", "component": "normal", "content": { "caption": "my caption" }, "styles": { "position": "left" } }, { "id": "doc-1b8i1ksh30", "identifier": "timeline.p", "component": "p", "content": { "text": "first paragraph" } }, { "id": "doc-1b8i1me1d0", "identifier": "timeline.p", "component": "p", "content": { "text": "second paragraph" } } ], "renditions": [ { "handle": "web", "content": "
\n

a title

\n

some lead

\n
\n
\n \n
my caption
\n
\n

first paragraph

\n

second

\n

and third one. :)

" }, { "handle": "mobile", "content": { "content": [ { "id": "doc-1b8i1ksh10", "identifier": "timeline.head", "component": "head", "content": { "title": "a title", "text": "some lead" } }, { "id": "doc-1b8i1ksh20", "identifier": "timeline.normal", "component": "normal", "content": { "caption": "my caption" }, "styles": { "position": "left" } }, { "id": "doc-1b8i1ksh30", "identifier": "timeline.p", "component": "p", "content": { "text": "first paragraph" } }, { "id": "doc-1b8i1me1d0", "identifier": "timeline.p", "component": "p", "content": { "text": "second paragraph" } } ], "design": { "name": "timeline", "version": "1.1.0" } } }, { "handle": "app", "error": { "message": "Processing of Channel 'app' for document '1' failed. Detailed error message…" } } ] } }, "CompositionApiRequestBody": { "type": "object", "example": { "fields": [ "systemdata", "metadata", "content", "html", "includes", "design" ], "metadata": { "preload": { "myMetadataProp": true } }, "resolveIncludes": true, "renderOptions": { "renderDirectiveInfo": true } }, "properties": { "fields": { "type": "array", "items": { "type": "string", "enum": [ "systemdata", "metadata", "content", "html", "includes", "design" ] } }, "metadata": { "type": "object", "additionalProperties": false, "properties": { "preload": { "type": "object" } } }, "resolveIncludes": { "type": "boolean" }, "renderOptions": { "type": "object", "additionalProperties": false, "properties": { "renderDirectiveInfo": { "type": "boolean" } } } } }, "CompositionApiResponse": { "type": "object", "properties": { "systemdata": { "$ref": "#/components/schemas/Systemdata" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "content": { "$ref": "#/components/schemas/Content" }, "includes": { "type": "array", "items": { "type": "object", "properties": { "componentId": { "type": "string" }, "directiveName": { "type": "string" }, "resolvedValue": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "component": { "type": "string" }, "content": { "type": "object" } } } } } } } } }, "html": { "type": "string" } }, "example": { "systemdata": { "projectId": 1, "channelId": 1, "documentId": 1, "contentType": "article", "documentType": "article", "publicationId": 1, "firstPublicationDate": "2022-03-16T14:08:11.000Z", "significantPublicationDate": "2022-10-26T07:25:00.000Z", "visiblePublicationDate": "2022-10-27T06:00:00.000Z", "updatedAt": "2023-03-18T16:32:04.170Z", "design": { "name": "timeline", "version": "1.1.0" } }, "content": [ { "id": "doc-1b8i1ksh10", "identifier": "timeline.head", "component": "head", "content": { "title": "a title", "text": "some lead" } }, { "id": "doc-2c95a77x14", "identifier": "timeline.teaser", "component": "teaser", "content": { "embed-teaser": { "service": "embed-teaser", "params": { "document": { "'$ref'": "document", "reference": { "id": 7 } } } } } } ], "metadata": { "title": "a title", "description": "some lead", "topic": { "'$ref'": "document", "reference": { "id": "5" }, "isPreloaded": true, "value": { "metadata": { "title": "Another title" }, "systemdata": { "projectId": 1, "channelId": 1, "documentId": 5, "contentType": "article", "documentType": "article", "publicationId": 7, "firstPublicationDate": "2022-03-16T14:08:11.000Z", "significantPublicationDate": "2022-10-26T07:25:00.000Z", "visiblePublicationDate": "2022-10-27T06:00:00.000Z", "updatedAt": "2023-03-18T17:32:04.170Z", "design": { "name": "timeline", "version": "1.1.0" } } } } }, "includes": [ { "componentId": "doc-2c95a77x14", "directiveName": "embed-teaser", "resolvedValue": { "content": [ { "id": "ref-7", "component": "p", "content": { "text": "Some text." } } ] } } ], "html": "
...
" } } } } }