{ "openapi": "3.1.0", "info": { "title": "DDM external API", "version": "1.0.0", "description": "Push documents into DDM from systems without a built-in connector, and take DDM content out to other systems. Every request carries an API key from Settings › API access as `Authorization: Bearer ddm_…`. A key acts as one person and has exactly their rights." }, "servers": [ { "url": "https://ddm.example.com/api/ext/v1" } ], "security": [ { "apiKey": [ "read" ] } ], "tags": [ { "name": "Documents" }, { "name": "Categories" }, { "name": "Groups" }, { "name": "Sync" }, { "name": "Reference data" } ], "paths": { "/documents": { "get": { "tags": [ "Documents" ], "summary": "List documents, oldest change first", "description": "A page of documents with `nextCursor` to the next. With `updatedSince` it is a change feed: keep the last `updatedAt` and ask again later.", "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Only these attributes, comma-separated; dots reach inside an object or a `titles` map. `id` always comes.", "schema": { "example": "id,name,titles.DE,currentVersion.versionNo", "type": "string", "maxLength": 2000 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` of the previous page.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only documents changed at or after this time (ISO 8601, with offset).", "schema": { "example": "2026-10-01T00:00:00Z", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "categoryId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "categoryRef", "in": "query", "required": false, "description": "The category by its external reference, instead of `categoryId`.", "schema": { "type": "string", "minLength": 1, "maxLength": 512, "example": "PIM-4711" } }, { "name": "deep", "in": "query", "required": false, "description": "With `categoryId` or `categoryRef`: include sub-categories.", "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } }, { "name": "externalRef", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 512 } }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 64 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "in_review", "approved", "archived" ] } }, { "name": "own", "in": "query", "required": false, "description": "Only documents pushed through this key's push source.", "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` for the next page; null on the last one." } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/documents/ref/{ref}": { "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "The calling system's reference, URL-encoded (a `/` is `%2F`).", "schema": { "type": "string", "maxLength": 512 } } ], "put": { "tags": [ "Documents" ], "summary": "Push a document — create or update it by reference", "description": "Idempotent: sending the same request again ends in one document, and identical bytes change nothing. Filed by the key's push source: its category mode, conflict mode, file filter and group mapping. Needs scope `write`.", "security": [ { "apiKey": [ "write" ] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "description": "The file. Up to the plan's upload limit." }, "metadata": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "File name, including the extension. Default: the uploaded file's name, or the last part of `fileUrl`.", "example": "Preisliste-2026.pdf", "type": "string", "minLength": 1, "maxLength": 200 }, "categoryPath": { "type": "string", "maxLength": 1000, "description": "Category path, parts separated by `/`. Missing categories are created (category mode \"mirror\").", "example": "Products/Brochures" }, "categoryIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Categories by DDM id. With `categoryRefs` too, the document is filed in all of them." }, "categoryRefs": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The calling system's own id. Unique per push source.", "example": "PIM-4711" }, "description": "Categories by their external reference. With `categoryIds` too, the document is filed in all of them.", "example": [ "PIM-CAT-12" ] }, "mimeType": { "description": "Overrides the type the upload or the download declared.", "example": "application/pdf", "type": "string", "maxLength": 200 }, "groupName": { "description": "An external group, mapped to a DDM group by the push source's group mapping; that group gets read access.", "type": "string", "maxLength": 200 }, "tags": { "description": "Replaces the document's tags.", "example": [ "Preise", "2026" ], "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "titles": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 32 }, "additionalProperties": { "type": "string", "maxLength": 200 }, "description": "Title per market code (the market's country code, e.g. DE). An empty string removes the title.", "example": { "DE": "Preisliste 2026", "AT": "Preisliste 2026" } }, "availableFrom": { "description": "Readers see the document from this time on. Null: no start.", "example": "2026-11-01T00:00:00Z", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "availableUntil": { "description": "Readers no longer see the document after this time. Null: no end.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "highlightFrom": { "description": "The document is highlighted from this time on.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "highlightUntil": { "description": "The highlight ends at this time.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "watermarked": { "description": "Stamp the reader's e-mail address across every page they view or download. PDFs and Office files only; a watermarked document cannot be shared by link.", "type": "boolean" } }, "description": "JSON, as a text part." } } }, "encoding": { "metadata": { "contentType": "application/json" } } }, "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "File name, including the extension. Default: the uploaded file's name, or the last part of `fileUrl`.", "example": "Preisliste-2026.pdf", "type": "string", "minLength": 1, "maxLength": 200 }, "categoryPath": { "type": "string", "maxLength": 1000, "description": "Category path, parts separated by `/`. Missing categories are created (category mode \"mirror\").", "example": "Products/Brochures" }, "categoryIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Categories by DDM id. With `categoryRefs` too, the document is filed in all of them." }, "categoryRefs": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The calling system's own id. Unique per push source.", "example": "PIM-4711" }, "description": "Categories by their external reference. With `categoryIds` too, the document is filed in all of them.", "example": [ "PIM-CAT-12" ] }, "mimeType": { "description": "Overrides the type the upload or the download declared.", "example": "application/pdf", "type": "string", "maxLength": 200 }, "groupName": { "description": "An external group, mapped to a DDM group by the push source's group mapping; that group gets read access.", "type": "string", "maxLength": 200 }, "tags": { "description": "Replaces the document's tags.", "example": [ "Preise", "2026" ], "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "titles": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 32 }, "additionalProperties": { "type": "string", "maxLength": 200 }, "description": "Title per market code (the market's country code, e.g. DE). An empty string removes the title.", "example": { "DE": "Preisliste 2026", "AT": "Preisliste 2026" } }, "availableFrom": { "description": "Readers see the document from this time on. Null: no start.", "example": "2026-11-01T00:00:00Z", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "availableUntil": { "description": "Readers no longer see the document after this time. Null: no end.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "highlightFrom": { "description": "The document is highlighted from this time on.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "highlightUntil": { "description": "The highlight ends at this time.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "watermarked": { "description": "Stamp the reader's e-mail address across every page they view or download. PDFs and Office files only; a watermarked document cannot be shared by link.", "type": "boolean" }, "fileUrl": { "type": "string", "format": "uri", "description": "HTTP(S) address DDM downloads the file from — up to the plan's maximum file size, like an upload. Must be reachable from DDM; redirects are not followed.", "example": "https://pim.example.com/files/4711.pdf" } }, "required": [ "fileUrl" ] } } } }, "responses": { "200": { "description": "Updated, unchanged or skipped", "content": { "application/json": { "schema": { "type": "object", "required": [ "outcome", "document" ], "properties": { "outcome": { "type": "string", "enum": [ "created", "versioned", "unchanged", "skipped" ], "description": "`created` a new document, `versioned` new bytes on an existing one (a new version, or in place under the source's \"overwrite\"), `unchanged` the same bytes as before, `skipped` left alone by the source's file filter or its conflict mode \"skip\"." }, "document": { "anyOf": [ { "$ref": "#/components/schemas/Document" }, { "type": "null" } ] } } } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "outcome", "document" ], "properties": { "outcome": { "type": "string", "enum": [ "created", "versioned", "unchanged", "skipped" ], "description": "`created` a new document, `versioned` new bytes on an existing one (a new version, or in place under the source's \"overwrite\"), `unchanged` the same bytes as before, `skipped` left alone by the source's file filter or its conflict mode \"skip\"." }, "document": { "anyOf": [ { "$ref": "#/components/schemas/Document" }, { "type": "null" } ] } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "413": { "$ref": "#/components/responses/E413" }, "415": { "$ref": "#/components/responses/E415" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } }, "get": { "tags": [ "Documents" ], "summary": "Get a document by reference", "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Only these attributes, comma-separated; dots reach inside an object or a `titles` map. `id` always comes.", "schema": { "example": "id,name,titles.DE,currentVersion.versionNo", "type": "string", "maxLength": 2000 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } }, "patch": { "tags": [ "Documents" ], "summary": "Change a document by reference", "security": [ { "apiKey": [ "write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "description": "`archived` takes the document out of distribution, `draft` brings it back. Approval statuses are set by the approval workflow only.", "type": "string", "enum": [ "archived", "draft" ] }, "shareable": { "description": "Whether readers may send, open elsewhere or download it.", "type": "boolean" }, "highlighted": { "type": "boolean" }, "availableFrom": { "description": "Readers see the document from this time on. Null: no start.", "example": "2026-11-01T00:00:00Z", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "availableUntil": { "description": "Readers no longer see the document after this time. Null: no end.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "highlightFrom": { "description": "The document is highlighted from this time on.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "highlightUntil": { "description": "The highlight ends at this time.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "watermarked": { "description": "Stamp the reader's e-mail address across every page they view or download. PDFs and Office files only; a watermarked document cannot be shared by link.", "type": "boolean" }, "tags": { "description": "Replaces the whole set.", "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "titles": { "description": "Merged per market: markets not named keep their title.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 32 }, "additionalProperties": { "type": "string", "maxLength": 200 }, "example": { "DE": "Preisliste 2026", "AT": "Preisliste 2026" } }, "categoryIds": { "description": "Replaces where the document is filed — with `categoryRefs` too, by all of them.", "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "categoryRefs": { "description": "Replaces where the document is filed, by external references — with `categoryIds` too, by all of them.", "example": [ "PIM-CAT-12" ], "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The calling system's own id. Unique per push source.", "example": "PIM-4711" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } }, "delete": { "tags": [ "Documents" ], "summary": "Delete a document by reference", "security": [ { "apiKey": [ "write" ] } ], "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/documents/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "put": { "tags": [ "Documents" ], "summary": "New bytes for a document by id", "description": "One of this key's push source is pushed as by its reference. Any other document — uploaded in the CMS, or another source's — gets a new version as an upload would. Needs scope `write`.", "security": [ { "apiKey": [ "write" ] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "description": "The file. Up to the plan's upload limit." }, "metadata": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "File name, including the extension. Default: the uploaded file's name, or the last part of `fileUrl`.", "example": "Preisliste-2026.pdf", "type": "string", "minLength": 1, "maxLength": 200 }, "categoryPath": { "type": "string", "maxLength": 1000, "description": "Category path, parts separated by `/`. Missing categories are created (category mode \"mirror\").", "example": "Products/Brochures" }, "categoryIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Categories by DDM id. With `categoryRefs` too, the document is filed in all of them." }, "categoryRefs": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The calling system's own id. Unique per push source.", "example": "PIM-4711" }, "description": "Categories by their external reference. With `categoryIds` too, the document is filed in all of them.", "example": [ "PIM-CAT-12" ] }, "mimeType": { "description": "Overrides the type the upload or the download declared.", "example": "application/pdf", "type": "string", "maxLength": 200 }, "groupName": { "description": "An external group, mapped to a DDM group by the push source's group mapping; that group gets read access.", "type": "string", "maxLength": 200 }, "tags": { "description": "Replaces the document's tags.", "example": [ "Preise", "2026" ], "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "titles": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 32 }, "additionalProperties": { "type": "string", "maxLength": 200 }, "description": "Title per market code (the market's country code, e.g. DE). An empty string removes the title.", "example": { "DE": "Preisliste 2026", "AT": "Preisliste 2026" } }, "availableFrom": { "description": "Readers see the document from this time on. Null: no start.", "example": "2026-11-01T00:00:00Z", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "availableUntil": { "description": "Readers no longer see the document after this time. Null: no end.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "highlightFrom": { "description": "The document is highlighted from this time on.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "highlightUntil": { "description": "The highlight ends at this time.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "watermarked": { "description": "Stamp the reader's e-mail address across every page they view or download. PDFs and Office files only; a watermarked document cannot be shared by link.", "type": "boolean" } }, "description": "JSON, as a text part." } } }, "encoding": { "metadata": { "contentType": "application/json" } } }, "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "File name, including the extension. Default: the uploaded file's name, or the last part of `fileUrl`.", "example": "Preisliste-2026.pdf", "type": "string", "minLength": 1, "maxLength": 200 }, "categoryPath": { "type": "string", "maxLength": 1000, "description": "Category path, parts separated by `/`. Missing categories are created (category mode \"mirror\").", "example": "Products/Brochures" }, "categoryIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Categories by DDM id. With `categoryRefs` too, the document is filed in all of them." }, "categoryRefs": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The calling system's own id. Unique per push source.", "example": "PIM-4711" }, "description": "Categories by their external reference. With `categoryIds` too, the document is filed in all of them.", "example": [ "PIM-CAT-12" ] }, "mimeType": { "description": "Overrides the type the upload or the download declared.", "example": "application/pdf", "type": "string", "maxLength": 200 }, "groupName": { "description": "An external group, mapped to a DDM group by the push source's group mapping; that group gets read access.", "type": "string", "maxLength": 200 }, "tags": { "description": "Replaces the document's tags.", "example": [ "Preise", "2026" ], "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "titles": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 32 }, "additionalProperties": { "type": "string", "maxLength": 200 }, "description": "Title per market code (the market's country code, e.g. DE). An empty string removes the title.", "example": { "DE": "Preisliste 2026", "AT": "Preisliste 2026" } }, "availableFrom": { "description": "Readers see the document from this time on. Null: no start.", "example": "2026-11-01T00:00:00Z", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "availableUntil": { "description": "Readers no longer see the document after this time. Null: no end.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "highlightFrom": { "description": "The document is highlighted from this time on.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "highlightUntil": { "description": "The highlight ends at this time.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "watermarked": { "description": "Stamp the reader's e-mail address across every page they view or download. PDFs and Office files only; a watermarked document cannot be shared by link.", "type": "boolean" }, "fileUrl": { "type": "string", "format": "uri", "description": "HTTP(S) address DDM downloads the file from — up to the plan's maximum file size, like an upload. Must be reachable from DDM; redirects are not followed.", "example": "https://pim.example.com/files/4711.pdf" } }, "required": [ "fileUrl" ] } } } }, "responses": { "200": { "description": "Versioned or unchanged", "content": { "application/json": { "schema": { "type": "object", "required": [ "outcome", "document" ], "properties": { "outcome": { "type": "string", "enum": [ "created", "versioned", "unchanged", "skipped" ], "description": "`created` a new document, `versioned` new bytes on an existing one (a new version, or in place under the source's \"overwrite\"), `unchanged` the same bytes as before, `skipped` left alone by the source's file filter or its conflict mode \"skip\"." }, "document": { "anyOf": [ { "$ref": "#/components/schemas/Document" }, { "type": "null" } ] } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "413": { "$ref": "#/components/responses/E413" }, "415": { "$ref": "#/components/responses/E415" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } }, "get": { "tags": [ "Documents" ], "summary": "Get a document", "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Only these attributes, comma-separated; dots reach inside an object or a `titles` map. `id` always comes.", "schema": { "example": "id,name,titles.DE,currentVersion.versionNo", "type": "string", "maxLength": 2000 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } }, "patch": { "tags": [ "Documents" ], "summary": "Change a document", "security": [ { "apiKey": [ "write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "description": "`archived` takes the document out of distribution, `draft` brings it back. Approval statuses are set by the approval workflow only.", "type": "string", "enum": [ "archived", "draft" ] }, "shareable": { "description": "Whether readers may send, open elsewhere or download it.", "type": "boolean" }, "highlighted": { "type": "boolean" }, "availableFrom": { "description": "Readers see the document from this time on. Null: no start.", "example": "2026-11-01T00:00:00Z", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "availableUntil": { "description": "Readers no longer see the document after this time. Null: no end.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "highlightFrom": { "description": "The document is highlighted from this time on.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "highlightUntil": { "description": "The highlight ends at this time.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "watermarked": { "description": "Stamp the reader's e-mail address across every page they view or download. PDFs and Office files only; a watermarked document cannot be shared by link.", "type": "boolean" }, "tags": { "description": "Replaces the whole set.", "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "titles": { "description": "Merged per market: markets not named keep their title.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 32 }, "additionalProperties": { "type": "string", "maxLength": 200 }, "example": { "DE": "Preisliste 2026", "AT": "Preisliste 2026" } }, "categoryIds": { "description": "Replaces where the document is filed — with `categoryRefs` too, by all of them.", "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "categoryRefs": { "description": "Replaces where the document is filed, by external references — with `categoryIds` too, by all of them.", "example": [ "PIM-CAT-12" ], "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The calling system's own id. Unique per push source.", "example": "PIM-4711" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } }, "delete": { "tags": [ "Documents" ], "summary": "Delete a document", "security": [ { "apiKey": [ "write" ] } ], "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/documents/ref/{ref}/content": { "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "The calling system's reference, URL-encoded (a `/` is `%2F`).", "schema": { "type": "string", "maxLength": 512 } } ], "get": { "tags": [ "Documents" ], "summary": "Download the file, by reference", "parameters": [ { "name": "versionId", "in": "query", "required": false, "description": "A specific version; default: the current one.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "The bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } }, "headers": { "ETag": { "schema": { "type": "string" } }, "Accept-Ranges": { "schema": { "type": "string" } }, "Content-Range": { "schema": { "type": "string" } } } }, "206": { "description": "Part of the bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } }, "headers": { "ETag": { "schema": { "type": "string" } }, "Accept-Ranges": { "schema": { "type": "string" } }, "Content-Range": { "schema": { "type": "string" } } } }, "304": { "description": "Not modified" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/documents/ref/{ref}/text": { "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "The calling system's reference, URL-encoded (a `/` is `%2F`).", "schema": { "type": "string", "maxLength": 512 } } ], "get": { "tags": [ "Documents" ], "summary": "The text of the current version, by reference", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "versionNo": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "language": { "type": [ "string", "null" ] }, "content": { "type": "string" } }, "required": [ "versionId", "versionNo", "language", "content" ], "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/documents/ref/{ref}/thumbnail": { "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "The calling system's reference, URL-encoded (a `/` is `%2F`).", "schema": { "type": "string", "maxLength": 512 } } ], "get": { "tags": [ "Documents" ], "summary": "The preview image, by reference", "parameters": [ { "name": "versionId", "in": "query", "required": false, "description": "A specific version; default: the current one.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "The image", "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } }, "headers": { "ETag": { "schema": { "type": "string" } }, "Accept-Ranges": { "schema": { "type": "string" } }, "Content-Range": { "schema": { "type": "string" } } } }, "304": { "description": "Not modified" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/documents/{id}/content": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Documents" ], "summary": "Download the file", "description": "Supports `Range` and `If-None-Match`. With a `published` key only documents that may leave the app (`shareable`) can be downloaded.", "parameters": [ { "name": "versionId", "in": "query", "required": false, "description": "A specific version; default: the current one.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "The bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } }, "headers": { "ETag": { "schema": { "type": "string" } }, "Accept-Ranges": { "schema": { "type": "string" } }, "Content-Range": { "schema": { "type": "string" } } } }, "206": { "description": "Part of the bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } }, "headers": { "ETag": { "schema": { "type": "string" } }, "Accept-Ranges": { "schema": { "type": "string" } }, "Content-Range": { "schema": { "type": "string" } } } }, "304": { "description": "Not modified" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/documents/{id}/text": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Documents" ], "summary": "The text of the current version", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "versionNo": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "language": { "type": [ "string", "null" ] }, "content": { "type": "string" } }, "required": [ "versionId", "versionNo", "language", "content" ], "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/documents/{id}/thumbnail": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Documents" ], "summary": "The preview image", "parameters": [ { "name": "versionId", "in": "query", "required": false, "description": "A specific version; default: the current one.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "The image", "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } }, "headers": { "ETag": { "schema": { "type": "string" } }, "Accept-Ranges": { "schema": { "type": "string" } }, "Content-Range": { "schema": { "type": "string" } } } }, "304": { "description": "Not modified" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/documents/{id}/access": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Documents" ], "summary": "Who may read the document", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Access" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } }, "put": { "tags": [ "Documents" ], "summary": "Replace the document's grants", "description": "The whole set of explicit grants, by group (`groupId` or `groupRef`) or person (`userEmail`). Needs `full` on the document. With `restrictToGrantedUsers`, only the people named may read it.", "security": [ { "apiKey": [ "write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "grants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "groupRef": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The calling system's own id. Unique per push source.", "example": "PIM-4711" }, "userEmail": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "level": { "type": "string", "enum": [ "none", "read", "full" ], "description": "`read`, `full`, or `none` — which takes away what a category higher up gives." } }, "required": [ "level" ] }, "description": "The whole set of explicit grants. A subject left out has none here, and inherits." }, "restrictToGrantedUsers": { "description": "Only the people named here may read it: every group that would reach it through its categories gets `none`.", "type": "boolean" } }, "required": [ "grants" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Access" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/documents/ref/{ref}/access": { "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "The calling system's reference, URL-encoded (a `/` is `%2F`).", "schema": { "type": "string", "maxLength": 512 } } ], "get": { "tags": [ "Documents" ], "summary": "Who may read the document", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Access" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } }, "put": { "tags": [ "Documents" ], "summary": "Replace the document's grants", "description": "The whole set of explicit grants, by group (`groupId` or `groupRef`) or person (`userEmail`). Needs `full` on the document.", "security": [ { "apiKey": [ "write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "grants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "groupRef": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The calling system's own id. Unique per push source.", "example": "PIM-4711" }, "userEmail": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "level": { "type": "string", "enum": [ "none", "read", "full" ], "description": "`read`, `full`, or `none` — which takes away what a category higher up gives." } }, "required": [ "level" ] }, "description": "The whole set of explicit grants. A subject left out has none here, and inherits." }, "restrictToGrantedUsers": { "description": "Only the people named here may read it: every group that would reach it through its categories gets `none`.", "type": "boolean" } }, "required": [ "grants" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Access" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/categories": { "get": { "tags": [ "Categories" ], "summary": "List categories, parents first", "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Only these attributes, comma-separated; dots reach inside an object or a `titles` map. `id` always comes.", "schema": { "example": "id,name,titles.DE,currentVersion.versionNo", "type": "string", "maxLength": 2000 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } } }, "post": { "tags": [ "Categories" ], "summary": "Create a category", "security": [ { "apiKey": [ "write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "parentId": { "description": "Absent or null: a top-level category, which needs an administrator as the acting user.", "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "parentRef": { "description": "The parent by its external reference, instead of `parentId`.", "type": "string", "minLength": 1, "maxLength": 512, "example": "PIM-4711" }, "tags": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "titles": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 32 }, "additionalProperties": { "type": "string", "maxLength": 200 }, "description": "Title per market code (the market's country code, e.g. DE). An empty string removes the title.", "example": { "DE": "Preisliste 2026", "AT": "Preisliste 2026" } } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/categories/ref/{ref}": { "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "The calling system's reference, URL-encoded (a `/` is `%2F`).", "schema": { "type": "string", "maxLength": 512 } } ], "put": { "tags": [ "Categories" ], "summary": "Create or update a category by reference", "security": [ { "apiKey": [ "write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "parentId": { "description": "Absent or null: a top-level category, which needs an administrator as the acting user.", "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "parentRef": { "description": "The parent by its external reference, instead of `parentId`.", "type": "string", "minLength": 1, "maxLength": 512, "example": "PIM-4711" }, "tags": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "titles": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 32 }, "additionalProperties": { "type": "string", "maxLength": 200 }, "description": "Title per market code (the market's country code, e.g. DE). An empty string removes the title.", "example": { "DE": "Preisliste 2026", "AT": "Preisliste 2026" } } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } }, "get": { "tags": [ "Categories" ], "summary": "Get a category by reference", "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Only these attributes, comma-separated; dots reach inside an object or a `titles` map. `id` always comes.", "schema": { "example": "id,name,titles.DE,currentVersion.versionNo", "type": "string", "maxLength": 2000 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } }, "patch": { "tags": [ "Categories" ], "summary": "Rename, move, re-tag or re-title a category by reference", "security": [ { "apiKey": [ "write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "parentId": { "description": "A uuid moves it, null makes it top-level, absent leaves it.", "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "parentRef": { "description": "Moves it under the category with this external reference, instead of `parentId`.", "type": "string", "minLength": 1, "maxLength": 512, "example": "PIM-4711" }, "tags": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "titles": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 32 }, "additionalProperties": { "type": "string", "maxLength": 200 }, "description": "Title per market code (the market's country code, e.g. DE). An empty string removes the title.", "example": { "DE": "Preisliste 2026", "AT": "Preisliste 2026" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } }, "delete": { "tags": [ "Categories" ], "summary": "Delete a category by reference, and everything below it", "security": [ { "apiKey": [ "write" ] } ], "parameters": [ { "name": "withDocuments", "in": "query", "required": false, "description": "Also delete the documents filed only here. Without it, a category that holds documents is refused with 409.", "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } } ], "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/categories/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Categories" ], "summary": "Get a category", "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Only these attributes, comma-separated; dots reach inside an object or a `titles` map. `id` always comes.", "schema": { "example": "id,name,titles.DE,currentVersion.versionNo", "type": "string", "maxLength": 2000 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } }, "patch": { "tags": [ "Categories" ], "summary": "Rename, move, re-tag or re-title a category", "security": [ { "apiKey": [ "write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "parentId": { "description": "A uuid moves it, null makes it top-level, absent leaves it.", "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "parentRef": { "description": "Moves it under the category with this external reference, instead of `parentId`.", "type": "string", "minLength": 1, "maxLength": 512, "example": "PIM-4711" }, "tags": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "titles": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 32 }, "additionalProperties": { "type": "string", "maxLength": 200 }, "description": "Title per market code (the market's country code, e.g. DE). An empty string removes the title.", "example": { "DE": "Preisliste 2026", "AT": "Preisliste 2026" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } }, "delete": { "tags": [ "Categories" ], "summary": "Delete a category and everything below it", "security": [ { "apiKey": [ "write" ] } ], "parameters": [ { "name": "withDocuments", "in": "query", "required": false, "description": "Also delete the documents filed only here. Without it, a category that holds documents is refused with 409.", "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } } ], "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/categories/{id}/access": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Categories" ], "summary": "Who may read the category", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Access" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } }, "put": { "tags": [ "Categories" ], "summary": "Replace the category's grants", "description": "The whole set of explicit grants, by group (`groupId` or `groupRef`) or person (`userEmail`). Needs `full` on the category. `none` takes away what a category above gives.", "security": [ { "apiKey": [ "write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "grants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "groupRef": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The calling system's own id. Unique per push source.", "example": "PIM-4711" }, "userEmail": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "level": { "type": "string", "enum": [ "none", "read", "full" ], "description": "`read`, `full`, or `none` — which takes away what a category higher up gives." } }, "required": [ "level" ] }, "description": "The whole set of explicit grants. A subject left out has none here, and inherits." } }, "required": [ "grants" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Access" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/categories/ref/{ref}/access": { "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "The calling system's reference, URL-encoded (a `/` is `%2F`).", "schema": { "type": "string", "maxLength": 512 } } ], "get": { "tags": [ "Categories" ], "summary": "Who may read the category", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Access" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } }, "put": { "tags": [ "Categories" ], "summary": "Replace the category's grants", "description": "The whole set of explicit grants, by group (`groupId` or `groupRef`) or person (`userEmail`). Needs `full` on the category.", "security": [ { "apiKey": [ "write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "grants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "groupRef": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The calling system's own id. Unique per push source.", "example": "PIM-4711" }, "userEmail": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "level": { "type": "string", "enum": [ "none", "read", "full" ], "description": "`read`, `full`, or `none` — which takes away what a category higher up gives." } }, "required": [ "level" ] }, "description": "The whole set of explicit grants. A subject left out has none here, and inherits." } }, "required": [ "grants" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Access" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/groups": { "get": { "tags": [ "Groups" ], "summary": "List groups, by name", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } } }, "post": { "tags": [ "Groups" ], "summary": "Create a group", "description": "Needs an administrator as the acting person.", "security": [ { "apiKey": [ "write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/groups/ref/{ref}": { "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "The calling system's reference, URL-encoded (a `/` is `%2F`).", "schema": { "type": "string", "maxLength": 512 } } ], "put": { "tags": [ "Groups" ], "summary": "Create or update a group by reference", "security": [ { "apiKey": [ "write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } }, "get": { "tags": [ "Groups" ], "summary": "Get a group by reference", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } }, "patch": { "tags": [ "Groups" ], "summary": "Rename a group by reference", "security": [ { "apiKey": [ "write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } }, "delete": { "tags": [ "Groups" ], "summary": "Delete a group by reference, with its memberships and grants", "security": [ { "apiKey": [ "write" ] } ], "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/groups/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Groups" ], "summary": "Get a group", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } }, "patch": { "tags": [ "Groups" ], "summary": "Rename a group", "security": [ { "apiKey": [ "write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } }, "delete": { "tags": [ "Groups" ], "summary": "Delete a group, with its memberships and grants", "security": [ { "apiKey": [ "write" ] } ], "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/sync": { "get": { "tags": [ "Sync" ], "summary": "Manifest of everything the key can see", "description": "Compare with your last copy to find what was deleted or is no longer visible.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "complete": { "type": "boolean", "description": "False past 50 000 documents: then do not delete by comparison." }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalRef": { "type": [ "string", "null" ] }, "sourceId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "status": { "type": "string" }, "currentVersionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "checksum": { "type": [ "string", "null" ] }, "categoryIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "externalRef", "sourceId", "status", "currentVersionId", "checksum", "categoryIds", "updatedAt" ], "additionalProperties": false } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "externalRef": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "parentId", "externalRef", "updatedAt" ], "additionalProperties": false } } }, "required": [ "generatedAt", "complete", "documents", "categories" ], "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/tags": { "get": { "tags": [ "Reference data" ], "summary": "Tags in use, most used first", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "uses": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "name", "uses" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/markets": { "get": { "tags": [ "Reference data" ], "summary": "Markets — their codes key every `titles` object", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Market" } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } } }, "post": { "tags": [ "Reference data" ], "summary": "Add the market for a country", "description": "A market that is already there is answered as it is, with 200. Needs an administrator as the acting person.", "security": [ { "apiKey": [ "write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Already there", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Market" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Market" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/markets/{code}": { "parameters": [ { "name": "code", "in": "path", "required": true, "description": "The market's country code.", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } } ], "get": { "tags": [ "Reference data" ], "summary": "Get a market by its country code", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Market" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } }, "patch": { "tags": [ "Reference data" ], "summary": "Rename a market, or make it the default", "description": "The country code does not change. Making one market the default ends it for the one before. Needs an administrator as the acting person.", "security": [ { "apiKey": [ "write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "isDefault": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Market" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } }, "delete": { "tags": [ "Reference data" ], "summary": "Remove a market, and every title given in it", "security": [ { "apiKey": [ "write" ] } ], "responses": { "204": { "description": "Removed" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "ddm__", "description": "An API key from Settings › API access. Scopes: `read`, `write`." } }, "schemas": { "Error": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "conflict", "gone", "too_large", "unsupported_media_type", "rate_limited", "internal" ], "description": "Stable, for programs to switch on." }, "message": { "type": "string", "description": "A sentence for people, in the language of `Accept-Language` (English or German)." }, "issues": { "description": "Per field, for a request that did not validate.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "Document": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$ref": "#/$defs/Document", "$defs": { "Document": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalRef": { "description": "The reference it was pushed with, if any.", "type": [ "string", "null" ] }, "sourceId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The source it came through: a push source, or a connector." }, "name": { "type": "string" }, "fileType": { "type": "string" }, "mimeType": { "type": [ "string", "null" ] }, "sizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "draft", "in_review", "approved", "archived" ] }, "shareable": { "type": "boolean" }, "highlighted": { "type": "boolean", "description": "Highlighted now: put forward by somebody, or within its highlight window." }, "availableFrom": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Readers see it from this time on." }, "availableUntil": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Readers no longer see it after this time." }, "highlightFrom": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "highlightUntil": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "watermarked": { "type": "boolean", "description": "Every copy a reader gets carries their e-mail address across each page." }, "titles": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Title per market code." }, "tags": { "type": "array", "items": { "type": "string" } }, "categoryIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Where it is filed — only categories the key can see." }, "categoryRefs": { "type": "array", "items": { "type": "string" }, "description": "The external references of those categories, where they have one." }, "currentVersion": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "versionNo": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "checksum": { "description": "SHA-256 of the bytes, hex.", "type": [ "string", "null" ] }, "sizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "mimeType": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "versionNo", "checksum", "sizeBytes", "mimeType", "createdAt" ], "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last change: bytes, metadata, tags or titles." } }, "required": [ "id", "externalRef", "sourceId", "name", "fileType", "mimeType", "sizeBytes", "status", "shareable", "highlighted", "availableFrom", "availableUntil", "highlightFrom", "highlightUntil", "watermarked", "titles", "tags", "categoryIds", "categoryRefs", "currentVersion", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "Category": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$ref": "#/$defs/Category", "$defs": { "Category": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalRef": { "type": [ "string", "null" ] }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "parentRef": { "description": "The parent's external reference, if it has one.", "type": [ "string", "null" ] }, "name": { "type": "string" }, "path": { "type": "string", "description": "Names from the top, joined by \" / \"." }, "depth": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sortIndex": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "titles": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "externalRef", "parentId", "parentRef", "name", "path", "depth", "sortIndex", "titles", "tags", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "Group": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$ref": "#/$defs/Group", "$defs": { "Group": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalRef": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "externalRef", "name", "description", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "Market": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$ref": "#/$defs/Market", "$defs": { "Market": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "code": { "type": "string", "description": "Country code — the key of every `titles` object." }, "name": { "type": "string" }, "locale": { "type": "string" }, "isDefault": { "type": "boolean" } }, "required": [ "id", "code", "name", "locale", "isDefault" ], "additionalProperties": false } } }, "Access": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$ref": "#/$defs/Access", "$defs": { "Access": { "type": "object", "properties": { "grants": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "groupRef": { "type": [ "string", "null" ] }, "userEmail": { "type": [ "string", "null" ] }, "level": { "type": "string", "enum": [ "none", "read", "full" ] }, "inherited": { "description": "Categories only: set on a category above, not on this one.", "type": "boolean" } }, "required": [ "level" ], "additionalProperties": false } } }, "required": [ "grants" ], "additionalProperties": false } } } }, "responses": { "E400": { "description": "The request is invalid — see `issues`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E401": { "description": "No key, or a key that is invalid, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E403": { "description": "The key may not do this: missing scope, the acting person lacks the rights, or the plan does not include the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E404": { "description": "Not there, or not visible to this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E409": { "description": "Conflicts with the current state — a running approval, a retention hold, a category that still holds documents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E413": { "description": "The file is larger than the plan allows, or storage is full.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E415": { "description": "Neither multipart/form-data nor application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E422": { "description": "The file could not be fetched from `fileUrl`, or could not be stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E429": { "description": "Too many requests with this key — see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }