> ## Documentation Index > Fetch the complete documentation index at: https://apidocs.document360.com/llms.txt > Use this file to discover all available pages before exploring further. # Update category content > Updates the body content of the latest draft version. If `auto_fork` is `true` and no draft exists, a new draft is automatically forked from the published version before applying the update. The `updated_by` field is required when using an M2M token. SAS tokens in media URLs are automatically stripped before persisting. Use `GET /v3/projects/{projectId}/categories/{categoryId}/content` with `raw` mode to retrieve content suitable for round-trip editing. ### Related endpoints **Next** - `POST /v3/projects/{project_id}/categories/{category_id}/publish` — Publishes the edit. **See also** - `GET /v3/projects/{project_id}/categories/{category_id}/content` — Reads the page content back. ### Adding a comment starts here (step 1 of 2) This endpoint writes the content. It is also **step 1 of adding a comment** — see `POST /v3/projects/{project_id}/categories/{category_id}/comments` for step 2. A comment is **two facts that must agree**: a marker in the content that highlights the annotated text, and the comment thread itself. Two endpoints write them, and both calls must carry the **same `comment_id`**. 1. **Add the marker** — `PATCH /v3/projects/{project_id}/categories/{category_id}/content` Send the content with the annotated text wrapped in an element carrying `data-comment-id=""`. Generate the id yourself (a GUID) — you reuse it in step 2. 2. **Create the thread** — `POST /v3/projects/{project_id}/categories/{category_id}/comments` Send that same value as `comment_id` in the body. **Order matters.** Step 2 checks the marker is present and returns `422` if it is not, so a thread can never exist without the text it annotates. The reverse is not enforced: a marker with no thread is an inert highlight, so if step 2 fails, either retry it or take the marker back out. The request examples on both operations use the same `comment_id` (`b7f3c1a0-5e42-4d18-9a6c-2f8091d3e547`) and the same annotated text (`single sign-on`), so you can copy step 1, then step 2, and the pair works unchanged. Comments are supported only on block-editor (Editor 3.0) content; any other editor is rejected with `422`. ## OpenAPI ````json PATCH /v3/projects/{project_id}/categories/{category_id}/content { "openapi": "3.0.1", "info": { "title": "Document360 Customer API", "description": "Document360 RESTful APIs let you integrate your documentation with your software — onboard readers, manage articles, automate publishing, and more.\n\nFull reference: [API Documentation](https://apidocs.document360.io/docs).\n\n## Authentication\nV3 authenticates with an **API key** — not the `api_token` used by V1/V2. Create one in the Document360 portal under **Settings → Knowledge base portal → API keys**, then click **Create API key**. (Projects that still have the older screen show two tabs; choose **Enhanced keys (v3)**, or pick **API v3** from the Create menu.)\n\nSend it in the `X-API-Key` header:\n\n```\nX-API-Key: d360_sk_...\n```\n\nThe plaintext key is shown **once**, at creation — only its hash is stored, so a lost key must be replaced rather than recovered. Each key carries a fixed portal role, content role and content-access scope, supports an optional expiry, and can be disabled or deleted at any time from the same screen. Treat it as an opaque string: it is a pre-shared secret, not an OAuth 2.0 access token, and must not be parsed.\n\nFor flows that act on behalf of a specific person, V3 also accepts an OAuth 2.0 bearer token carrying the `customerApi` scope.\n\nAPI access is part of your subscription plan. If your plan does not include it, every endpoint returns `403` with the error code `FEATURE_NOT_IN_LICENSE` — including for keys created while an earlier plan was active. Contact your Customer Success Manager or `support@document360.com` to enable it.\n\n> **Note on terminology:** V1/V2 call these *API tokens* and manage them under **Settings → Knowledge base portal → API tokens**. V3 keys are a separate credential with their own screen, roles and scope — a V1/V2 token will not authenticate a V3 request.\n\n## Rate Limits\nAll endpoints are rate-limited per API key per project, with separate limits for reads (`GET`/`HEAD`) and writes (`POST`/`PUT`/`PATCH`/`DELETE`). Default limits vary by plan. When rate-limited, responses include `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. Use exponential backoff with jitter for optimal retry behavior.", "termsOfService": "https://document360.com/terms", "contact": { "name": "Document360 Support", "url": "https://document360.io/contact-us/", "email": "support@document360.com" }, "license": { "name": "Document360 API Terms of Use", "url": "https://document360.com/terms" }, "version": "3.0.0" }, "servers": [ { "url": "https://apihub.document360.io", "description": "Document 360 API Hub" }, { "url": "https://apihub.us.document360.io", "description": "Document360 API Hub - US data center" }, { "url": "https://apihub.{private_hosting}.document360.io", "description": "Private hosting - Please provide the subdomain name.", "variables": { "private_hosting": { "default": "domain", "description": "Sub domain for private hosting" } } } ], "security": [ { "ApiKey": [] }, { "Bearer": [ "customerApi" ] } ], "tags": [ { "name": "Projects", "description": "List and manage knowledge base projects. Export and import project documentation, and manage project-level site customization such as custom CSS and JavaScript." }, { "name": "Projects > Import & export", "description": "Start a project export or import and poll the resulting background operation for completion." }, { "name": "Workspaces", "description": "Manage workspaces and access workspace-scoped categories and articles." }, { "name": "Workspaces > AI", "description": "Query the workspace with Eddy AI, submit feedback on AI answers, and read that feedback with its conversation." }, { "name": "Articles", "description": "Create, read, update, and delete knowledge base articles and their settings, including bulk operations." }, { "name": "Articles > Publishing & workflow", "description": "Publish and unpublish articles (single and bulk) and update the article workflow status." }, { "name": "Articles > Versions", "description": "List, fork, and delete article versions." }, { "name": "Articles > Attachments", "description": "Manage the files attached to an article — list, upload, and delete article attachments." }, { "name": "Articles > Content drafts", "description": "(Internal) Stage AI-generated article content with an Accept/Reject review lifecycle — used by Eddy Copilot to preview content before committing to the live article body." }, { "name": "Articles > Labels", "description": "Read and set the labels associated with an article." }, { "name": "Articles > Comments", "description": "Read and create the comment threads authors and reviewers leave on an article's content, and reply to them. Each comment id matches the `data-comment-id` attribute of the corresponding marker in the raw article content, so adding a text-anchored comment takes two calls: update the content with the marker, then create the thread with the same id." }, { "name": "Categories", "description": "Manage the category hierarchy that organizes articles. Create, update, and delete categories and their settings, including bulk operations." }, { "name": "Categories > Page category", "description": "Read and update the content body of page-type categories, including bulk content updates." }, { "name": "Categories > Publishing & workflow", "description": "Publish and unpublish categories (single and bulk) and update the category workflow status." }, { "name": "Categories > Versions", "description": "List, fork, and delete category versions." }, { "name": "Categories > Labels", "description": "Read and set the labels associated with a category." }, { "name": "Categories > Comments", "description": "Read and create the comment threads authors and reviewers leave on a page category's content, and reply to them. Only page-type categories carry content, so other category types return `404`. Adding a text-anchored comment takes two calls: update the content with the marker, then create the thread with the same id." }, { "name": "ArticleTemplates", "description": "Manage reusable article templates — per-language article skeletons that authors and AI tools (such as Eddy Copilot) can apply when starting a new article.", "x-displayName": "Article templates" }, { "name": "Content reuse > Glossaries", "description": "Manage glossary entries — terminology definitions referenced inside articles via merge codes (`{{glossary.name}}`) and rendered as tooltips on the public KB." }, { "name": "Content reuse > Snippets", "description": "Manage reusable snippets — markdown or WYSIWYG content fragments referenced across articles via merge codes (`{{snippet.name}}`)." }, { "name": "Content reuse > Variables", "description": "Manage reusable variables — short text values referenced across articles via merge codes (`{{variable.name}}`)." }, { "name": "AiWriterStyleGuides", "description": "Retrieve AI writer style guides configured for the project — voice / tone instructions Eddy Copilot follows when generating article content. Used to let users pick a style before kicking off generation.", "x-displayName": "AI writer style guides" }, { "name": "RedirectRules", "description": "Manage article-redirection rules — 301/302 redirects from old article URLs to new locations after renames or restructures.", "x-displayName": "Redirect rules" }, { "name": "Tags", "description": "Manage tags — labels used to classify articles, categories, and files for filtering and discovery." }, { "name": "Labels", "description": "Manage labels shown on the article list and category tree. (Associating labels with a specific article or category lives under Articles and Categories.)" }, { "name": "MirroredArticles", "description": "List, read and create mirrored articles — read-only copies of a source article placed in other categories or workspaces of the project, including bulk mirroring." }, { "name": "CustomFields", "description": "Retrieve the custom field definitions configured for the project. Custom field values are read and written through the article and category settings endpoints.", "x-displayName": "Custom fields" }, { "name": "ApiReferences", "description": "Import, resync, and publish OpenAPI/Swagger specifications for API reference documentation.", "x-displayName": "API references" }, { "name": "ApiReferences > Logs", "description": "Monitor API reference import logs and inspect individual log entries." }, { "name": "Drive", "description": "Search Drive and retrieve files associated with an article, and track Drive background tasks." }, { "name": "Drive > Folders", "description": "Create, read, update, and delete Drive folders." }, { "name": "Drive > Files", "description": "Upload, copy, move, delete, and tag Drive files." }, { "name": "Drive > Image drafts", "description": "(Internal) Stage uploaded or AI-generated images (committed to Drive and associated with a staged article draft) — used by Eddy Copilot." }, { "name": "Readers", "description": "Manage reader accounts, invitations, and access scopes for private documentation." }, { "name": "Readers > Groups", "description": "Create, read, update, and delete reader groups." }, { "name": "Users", "description": "Manage users, their portal and content roles, and consolidated (effective) permissions within a project." }, { "name": "Users > Groups", "description": "Manage user groups, their portal role, and consolidated (effective) group permissions." }, { "name": "Roles", "description": "Create, read, update, and delete portal and content roles, list the users assigned to a role, and retrieve the permission dependency matrix." }, { "name": "ContentAccess", "description": "Manage per-node content-access permissions — grant, allow, deny, and inheritance overrides for users and groups against specific versions, languages, categories, or articles, plus version/language site protection.", "x-displayName": "Content access" }, { "name": "ContentAccess > Eligibility", "description": "List the readers and groups eligible to be granted content access." }, { "name": "Languages", "description": "Retrieve configured languages for a workspace." }, { "name": "Translations", "description": "Query translation status of articles across languages." }, { "name": "Operations", "description": "Track asynchronous operations — long-running tasks (bulk updates, merges, exports) accepted with `202 Accepted` and an `Operation-Location` header. Poll until the operation reaches a terminal status, honouring the `Retry-After` header." }, { "name": "AgentAssist", "description": "Back end for the Document360 Zendesk app's per-agent mode: workspace, category, article, search and Eddy AI reads executed as the signed-in support agent, plus article and category creation attributed to them.", "x-displayName": "Agent assist (Zendesk)" }, { "name": "ZendeskAppAuth", "description": "(Internal) Per-agent Document360 sign-in for the Zendesk app: begin a sign-in, receive the Identity callback, claim the agent's session handle, and check or end that session.", "x-displayName": "Zendesk app sign-in" }, { "name": "ZendeskAppAttestation", "description": "(Internal) The Zendesk app's signed background page: verifies the app token Zendesk signs for the agent at the keyboard and hands the app a short-lived agent pass that lets a sign-in complete silently.", "x-displayName": "Zendesk app attestation" }, { "name": "ZendeskAppConnect", "description": "(Internal) Completes connecting a project's Zendesk account for silent agent sign-in: the OAuth callback Zendesk redirects the approving admin to.", "x-displayName": "Zendesk account connection" }, { "name": "Analytics > Articles", "description": "View article performance metrics including views, top articles, reader locations, and category breakdowns." }, { "name": "Analytics > Search", "description": "View search usage metrics including top keywords, no-result queries, and bounced searches." }, { "name": "Analytics > AI search", "description": "View AI-powered search metrics including usage trends, most-referenced articles, and trending topics." }, { "name": "FeedbackManagement", "description": "Manage reader feedback on articles and page categories — list it, read a record, page through its team discussions, and update its status (including closing it) and assignee to sync it with external issue trackers.", "x-displayName": "Feedback management" }, { "name": "Analytics > Feedback", "description": "View reader feedback trends across articles, including top-performing articles and feedback keywords." } ], "externalDocs": { "description": "Document360 API Documentation", "url": "https://apidocs.document360.io/docs" }, "x-tagGroups": [ { "name": "Workspace", "tags": [ "Projects", "Projects > Import & export", "Workspaces", "Workspaces > AI" ] }, { "name": "Content", "tags": [ "Articles", "Articles > Publishing & workflow", "Articles > Versions", "Articles > Attachments", "Articles > Content drafts", "Articles > Labels", "Categories", "Categories > Page category", "Categories > Publishing & workflow", "Categories > Versions", "Categories > Labels", "ArticleTemplates", "AiWriterStyleGuides", "RedirectRules", "Tags", "Labels", "ApiReferences", "ApiReferences > Logs", "FeedbackManagement" ] }, { "name": "Content reuse", "tags": [ "Content reuse > Glossaries", "Content reuse > Snippets", "Content reuse > Variables" ] }, { "name": "Media", "tags": [ "Drive", "Drive > Folders", "Drive > Files", "Drive > Image drafts" ] }, { "name": "Access", "tags": [ "Readers", "Readers > Groups", "Users", "Users > Groups", "Roles", "ContentAccess", "ContentAccess > Eligibility" ] }, { "name": "Localization", "tags": [ "Languages", "Translations" ] }, { "name": "Operations", "tags": [ "Operations" ] }, { "name": "Integrations", "tags": [ "AgentAssist", "ZendeskAppAuth", "ZendeskAppAttestation", "ZendeskAppConnect" ] }, { "name": "Analytics", "tags": [ "Analytics > Articles", "Analytics > Search", "Analytics > AI search", "Analytics > Feedback" ] } ], "paths": { "/v3/projects/{project_id}/categories/{category_id}/content": { "patch": { "tags": [ "Categories > Page category" ], "summary": "Update category content.", "description": "Updates the body content of the latest draft version. If `auto_fork` is `true` and no draft exists,\r\na new draft is automatically forked from the published version before applying the update. The `updated_by`\r\nfield is required when using an M2M token. SAS tokens in media URLs are automatically stripped before\r\npersisting. Use `GET /v3/projects/{projectId}/categories/{categoryId}/content` with `raw` mode to\r\nretrieve content suitable for round-trip editing.\n\n### Related endpoints\n\n**Next**\n- `POST /v3/projects/{project_id}/categories/{category_id}/publish` — Publishes the edit.\n\n**See also**\n- `GET /v3/projects/{project_id}/categories/{category_id}/content` — Reads the page content back.\n\n### Adding a comment starts here (step 1 of 2)\n\nThis endpoint writes the content. It is also **step 1 of adding a comment** — see\n`POST /v3/projects/{project_id}/categories/{category_id}/comments` for step 2.\n\nA comment is **two facts that must agree**: a marker in the content that highlights the annotated text, and\nthe comment thread itself. Two endpoints write them, and both calls must carry the **same `comment_id`**.\n\n1. **Add the marker** — `PATCH /v3/projects/{project_id}/categories/{category_id}/content`\n Send the content with the annotated text wrapped in an element carrying `data-comment-id=\"\"`.\n Generate the id yourself (a GUID) — you reuse it in step 2.\n2. **Create the thread** — `POST /v3/projects/{project_id}/categories/{category_id}/comments`\n Send that same value as `comment_id` in the body.\n\n**Order matters.** Step 2 checks the marker is present and returns `422` if it is not, so a thread can never\nexist without the text it annotates. The reverse is not enforced: a marker with no thread is an inert\nhighlight, so if step 2 fails, either retry it or take the marker back out.\n\nThe request examples on both operations use the same `comment_id` (`b7f3c1a0-5e42-4d18-9a6c-2f8091d3e547`) and\nthe same annotated text (`single sign-on`), so you can copy step 1, then step 2, and\nthe pair works unchanged.\n\nComments are supported only on block-editor (Editor 3.0) content; any other editor is rejected with `422`.", "operationId": "updateCategoryContent", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/CategoryId" }, { "$ref": "#/components/parameters/LangCode" } ], "requestBody": { "description": "Updated category content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCategoryContentRequest" }, "example": "Document360

Your Zendesk account is connected to Document360. You can close this window.

", "examples": { "Update category content": { "summary": "Updates the title and content of a category. Uses auto_fork to create a new draft version, authored by updated_by, if the category is published.", "value": { "title": "Getting Started", "content": "# Getting Started\nUpdated guide with improved onboarding steps.", "content_type": null, "version_number": null, "translation_option": null, "source": null, "updated_by": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d", "auto_fork": true } } } } } }, "responses": { "200": { "description": "Category content updated successfully.", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests allowed in the current time window for this request's bucket. Read requests (GET/HEAD) and write requests (POST/PUT/PATCH/DELETE) have independent limits, applied per caller (API key or user) per project.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current time window. When this reaches 0, subsequent requests receive a 429 response.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryContentResponseApiResponse" }, "examples": { "Category content updated successfully": { "summary": "Returns the updated category content with the new version details.", "value": { "data": { "id": "9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d", "title": "Getting Started", "content": "# Getting Started\nUpdated guide with improved onboarding steps and new screenshots.", "html_content": "

Getting Started

\n

Updated guide with improved onboarding steps and new screenshots.

", "parent_category_id": null, "workspace_id": "1c2d3e4f-5a6b-7c8d-9e0f-a1b2c3d4e5f6", "version_number": 3, "public_version": 2, "latest_version": 3, "enable_rtl": false, "hidden": false, "status": "draft", "version_type": null, "created_by": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d", "created_at": "2025-03-01T09:00:00Z", "modified_at": "2025-08-20T15:45:00Z", "modified_by": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d", "slug": "getting-started", "is_fallback_content": false, "content_type": "markdown", "current_workflow_status_id": "b7e2a1d4-3f56-4c89-9d0e-1a2b3c4d5e6f", "stale_status": { "article_stale_status": "fresh", "stale_reason": "", "expired_at": "2026-01-31T05:10:26Z", "is_from_document_settings": false, "expire_days": 30 }, "content_hash": "sha256:9f2c5a1d8e3b4c6f7a0918273645dacb5e1f2a3b4c5d6e7f8091a2b3c4d5e6f7" }, "success": true, "request_id": "req_abc123def456", "errors": null, "warnings": null } } } } }, "links": { "publishCategory": { "operationId": "publishCategory", "description": "Publishes the edit." }, "addComment": { "operationId": "createCategoryComment", "parameters": { "project_id": "$request.path.project_id", "category_id": "$request.path.category_id" }, "description": "Step 2 — create the comment thread for the marker just written into this page category, using the same comment_id." } } }, "401": { "description": "Authentication token is missing or invalid.", "headers": { "WWW-Authenticate": { "description": "Indicates the authentication scheme required. Returns `Bearer` with optional `error` and `error_description` parameters per RFC 6750.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/V3ProblemDetails" }, { "type": "object", "properties": { "type": { "enum": [ "https://apidocs.document360.io/apidocs/errors/unauthorized" ], "type": "string", "description": "RFC 7807 error type URI. Always `https://apidocs.document360.io/apidocs/errors/unauthorized` for 401 responses." }, "status": { "enum": [ 401 ], "type": "integer", "description": "HTTP status code. Always `401` for this response.", "format": "int32" } } } ] }, "examples": { "Missing or invalid token": { "summary": "Authentication token is missing or invalid.", "value": { "type": "https://apidocs.document360.io/apidocs/errors/unauthorized", "title": "Unauthorized.", "status": 401, "detail": "The authentication token is missing or has expired.", "instance": null, "trace_id": "req_abc123def456", "errors": [ { "code": "UNAUTHORIZED", "message": "Bearer token is missing or invalid.", "field": null, "details": null } ], "warnings": null } } } } } }, "403": { "description": "Token lacks the required scope or content permission, including the publish permission needed to change `hidden`.", "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/V3ProblemDetails" }, { "type": "object", "properties": { "type": { "enum": [ "https://apidocs.document360.io/apidocs/errors/forbidden" ], "type": "string", "description": "RFC 7807 error type URI. Always `https://apidocs.document360.io/apidocs/errors/forbidden` for 403 responses." }, "status": { "enum": [ 403 ], "type": "integer", "description": "HTTP status code. Always `403` for this response.", "format": "int32" } } } ] }, "examples": { "Insufficient permissions": { "summary": "Insufficient permissions for this resource.", "value": { "type": "https://apidocs.document360.io/apidocs/errors/forbidden", "title": "Forbidden.", "status": 403, "detail": "You do not have permission to perform this action.", "instance": null, "trace_id": "req_abc123def456", "errors": [ { "code": "FORBIDDEN", "message": "Insufficient permissions for this project.", "field": null, "details": null } ], "warnings": null } } } } } }, "404": { "description": "Category not found.", "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/V3ProblemDetails" }, { "type": "object", "properties": { "type": { "enum": [ "https://apidocs.document360.io/apidocs/errors/resource-not-found" ], "type": "string", "description": "RFC 7807 error type URI. Always `https://apidocs.document360.io/apidocs/errors/resource-not-found` for 404 responses." }, "status": { "enum": [ 404 ], "type": "integer", "description": "HTTP status code. Always `404` for this response.", "format": "int32" } } } ] }, "examples": { "Resource not found": { "summary": "The requested resource does not exist.", "value": { "type": "https://apidocs.document360.io/apidocs/errors/resource-not-found", "title": "Resource not found.", "status": 404, "detail": "The requested resource was not found.", "instance": null, "trace_id": "req_abc123def456", "errors": [ { "code": "RESOURCE_NOT_FOUND", "message": "Resource not found.", "field": null, "details": null } ], "warnings": null } } } } } }, "409": { "description": "The category exists but its type carries no content — only Page categories do, or the category's language is archived and cannot be modified.", "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/V3ProblemDetails" }, { "type": "object", "properties": { "type": { "enum": [ "https://apidocs.document360.io/apidocs/errors/conflict" ], "type": "string", "description": "RFC 7807 error type URI. Always `https://apidocs.document360.io/apidocs/errors/conflict` for 409 responses." }, "status": { "enum": [ 409 ], "type": "integer", "description": "HTTP status code. Always `409` for this response.", "format": "int32" } } } ] }, "examples": { "Conflict": { "summary": "The operation conflicts with the current state of the resource.", "value": { "type": "https://apidocs.document360.io/apidocs/errors/conflict", "title": "Conflict.", "status": 409, "detail": "The operation conflicts with the current state of the resource.", "instance": null, "trace_id": "req_abc123def456", "errors": [ { "code": "CONFLICT", "message": "A resource with the same identifier already exists.", "field": null, "details": null } ], "warnings": null } } } } } }, "422": { "description": "Validation failed.", "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/V3ProblemDetails" }, { "type": "object", "properties": { "type": { "enum": [ "https://apidocs.document360.io/apidocs/errors/validation-error" ], "type": "string", "description": "RFC 7807 error type URI. Always `https://apidocs.document360.io/apidocs/errors/validation-error` for 422 responses." }, "status": { "enum": [ 422 ], "type": "integer", "description": "HTTP status code. Always `422` for this response.", "format": "int32" } } } ] }, "examples": { "Validation failed": { "summary": "One or more request fields failed validation.", "value": { "type": "https://apidocs.document360.io/apidocs/errors/validation-error", "title": "Validation Error", "status": 422, "detail": "One or more fields failed validation.", "instance": null, "trace_id": "req_abc123def456", "errors": [ { "code": "VALIDATION_ERROR", "message": "The field is required.", "field": "name", "details": null } ], "warnings": null } } } } } }, "400": { "description": "The request body is malformed or contains invalid JSON.", "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/V3ProblemDetails" }, { "type": "object", "properties": { "type": { "enum": [ "https://apidocs.document360.io/apidocs/errors/bad-request" ], "type": "string", "description": "RFC 7807 error type URI. Always `https://apidocs.document360.io/apidocs/errors/bad-request` for 400 responses." }, "status": { "enum": [ 400 ], "type": "integer", "description": "HTTP status code. Always `400` for this response.", "format": "int32" } } } ] }, "examples": { "Malformed request body": { "summary": "The request body could not be parsed.", "value": { "type": "https://apidocs.document360.io/apidocs/errors/bad-request", "title": "Bad Request.", "status": 400, "detail": "The request body is malformed or contains invalid JSON.", "instance": null, "trace_id": "req_abc123def456", "errors": [ { "code": "BAD_REQUEST", "message": "Could not parse the request body. Ensure it is valid JSON.", "field": null, "details": null } ], "warnings": null } } } } } }, "429": { "description": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request. Use exponential backoff with jitter for optimal retry behavior.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Limit": { "description": "The maximum number of requests allowed in the current time window for this request's bucket. Read requests (GET/HEAD) and write requests (POST/PUT/PATCH/DELETE) have independent limits, applied per caller (API key or user) per project. Read limits are typically higher than write limits.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current time window. When this reaches 0, subsequent requests will receive a 429 response.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "Number of seconds until the current rate limit window resets.", "schema": { "type": "integer", "format": "int64" } } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/V3ProblemDetails" }, { "type": "object", "properties": { "type": { "enum": [ "https://apidocs.document360.io/apidocs/errors/too-many-requests" ], "type": "string", "description": "RFC 7807 error type URI. Always `https://apidocs.document360.io/apidocs/errors/too-many-requests` for 429 responses." }, "status": { "enum": [ 429 ], "type": "integer", "description": "HTTP status code. Always `429` for this response.", "format": "int32" } } } ] }, "examples": { "Rate limit exceeded": { "summary": "Rate limit exceeded.", "value": { "type": "https://apidocs.document360.io/apidocs/errors/too-many-requests", "title": "Too Many Requests.", "status": 429, "detail": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.", "instance": null, "trace_id": "req_abc123def456", "errors": [ { "code": "TOO_MANY_REQUESTS", "message": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.", "field": null, "details": null } ], "warnings": null } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/V3ProblemDetails" }, { "type": "object", "properties": { "type": { "enum": [ "https://apidocs.document360.io/apidocs/errors/internal-server-error" ], "type": "string", "description": "RFC 7807 error type URI. Always `https://apidocs.document360.io/apidocs/errors/internal-server-error` for 500 responses." }, "status": { "enum": [ 500 ], "type": "integer", "description": "HTTP status code. Always `500` for this response.", "format": "int32" } } } ] }, "examples": { "Unexpected server error": { "summary": "Unexpected server error.", "value": { "type": "https://apidocs.document360.io/apidocs/errors/internal-server-error", "title": "Internal Server Error.", "status": 500, "detail": "An unexpected error occurred. Please try again or contact support.", "instance": null, "trace_id": "req_abc123def456", "errors": [ { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred.", "field": null, "details": null } ], "warnings": null } } } } } } }, "security": [ { "ApiKey": [] }, { "Bearer": [ "customerApi" ] } ], "x-related-endpoints": [ { "relationship": "related", "method": "GET", "path": "/v3/projects/{project_id}/categories/{category_id}/content", "operationId": "getCategoryContent", "description": "Reads the page content back." }, { "relationship": "next", "method": "POST", "path": "/v3/projects/{project_id}/categories/{category_id}/publish", "operationId": "publishCategory", "description": "Publishes the edit." } ] } } }, "components": { "parameters": { "ProjectId": { "name": "project_id", "in": "path", "description": "The unique identifier of the project. Retrieve project IDs from `GET /v3/projects`.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d" } }, "CategoryId": { "name": "category_id", "in": "path", "description": "The unique identifier of the category. Retrieve category IDs from `GET /v3/projects/{projectId}/categories`.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "b4c5d6e7-f8a9-0b1c-2d3e-4f5a6b7c8d9e" } }, "LangCode": { "name": "lang_code", "in": "query", "description": "ISO 639-1 language code (e.g., `en`, `fr`). Defaults to the project's primary language if omitted.", "schema": { "pattern": "^[a-z]{2,3}(-[A-Za-z0-9]{2,8}){0,2}$", "type": "string", "format": "language-tag", "example": "en" } } }, "schemas": { "UpdateCategoryContentRequest": { "type": "object", "properties": { "title": { "type": "string", "description": "Updated title of the category.", "nullable": true }, "content": { "type": "string", "description": "Updated content body.", "nullable": true }, "content_type": { "allOf": [ { "$ref": "#/components/schemas/ContentType" } ], "description": "The format of `content`, for page categories written in Editor 3.0 (which are always stored as `block`): `block` (the default when omitted) — `content` is the page HTML; `markdown` — `content` is DFM markdown, the format GET returns in `content`. `wysiwyg` is rejected with a 422. Ignored for all other categories.", "nullable": true, "example": "markdown" }, "version_number": { "type": "integer", "description": "Version number to base the update on.", "format": "int32", "nullable": true }, "translation_option": { "allOf": [ { "$ref": "#/components/schemas/TranslationOption" } ], "description": "Translation handling option for the update.", "nullable": true }, "source": { "type": "string", "description": "Source of the update (e.g., editor, API).", "nullable": true }, "updated_by": { "type": "string", "description": "The identifier of the user making the update. Required for API key and API token (M2M) authentication; when `auto_fork` forks a published version, this user becomes the author of the new draft. When using a user access token (OAuth), this field is ignored — the user ID is resolved from the token. Retrieve user IDs from `GET /v3/projects/{projectId}/users`.", "nullable": true, "example": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d" }, "auto_fork": { "type": "boolean", "description": "When true, automatically forks the category if it is published, instead of returning an error. With an API key or API token (M2M), also send `updated_by` — the request is rejected with 422 without it.", "nullable": true } }, "additionalProperties": false, "description": "Request to update category content." }, "CategoryContentResponseApiResponse": { "required": [ "data", "request_id", "success" ], "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/CategoryContentResponse" } ], "description": "Response data payload." }, "success": { "type": "boolean", "description": "Whether the API request was successful.", "readOnly": true }, "request_id": { "minLength": 1, "type": "string", "description": "Unique identifier for request tracing and correlation.", "readOnly": true }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ApiError" }, "description": "List of errors if the request failed.", "nullable": true }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ApiWarning" }, "description": "List of non-fatal warnings from the request.", "nullable": true } }, "additionalProperties": false, "description": "Generic API response wrapper containing typed data." }, "V3ProblemDetails": { "required": [ "status", "title", "type" ], "type": "object", "properties": { "type": { "minLength": 1, "enum": [ "https://apidocs.document360.io/apidocs/errors/bad-request", "https://apidocs.document360.io/apidocs/errors/unauthorized", "https://apidocs.document360.io/apidocs/errors/forbidden", "https://apidocs.document360.io/apidocs/errors/resource-not-found", "https://apidocs.document360.io/apidocs/errors/conflict", "https://apidocs.document360.io/apidocs/errors/validation-error", "https://apidocs.document360.io/apidocs/errors/too-many-requests", "https://apidocs.document360.io/apidocs/errors/internal-server-error" ], "type": "string", "description": "URI reference identifying the error type (links to documentation)." }, "title": { "minLength": 1, "type": "string", "description": "Short human-readable summary of the error type." }, "status": { "enum": [ 400, 401, 403, 404, 409, 422, 429, 500 ], "type": "integer", "description": "HTTP status code.", "format": "int32" }, "detail": { "type": "string", "description": "Human-readable explanation specific to this occurrence.", "nullable": true }, "instance": { "type": "string", "description": "URI of the request that generated the error.", "nullable": true }, "trace_id": { "type": "string", "description": "Request trace identifier for correlation.", "nullable": true }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ApiError" }, "description": "Structured list of specific errors (extension field).", "nullable": true }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ApiWarning" }, "description": "Non-fatal warnings (extension field).", "nullable": true } }, "additionalProperties": false, "description": "RFC 7807 Problem Details response for V3 API errors.\r\nContent-Type: application/problem+json" }, "ContentType": { "enum": [ "markdown", "wysiwyg", "block" ], "type": "string", "description": "The editor content type used for an article.", "x-enumNames": [ "Markdown", "Wysiwyg", "Block" ], "x-enum-varnames": [ "Markdown", "Wysiwyg", "Block" ], "x-ms-enum": { "name": "ContentType", "modelAsString": true } }, "TranslationOption": { "enum": [ "none", "needTranslation", "translated", "inProgress" ], "type": "string", "description": "The translation status of an article.", "x-enumNames": [ "None", "NeedTranslation", "Translated", "InProgress" ], "x-enum-varnames": [ "None", "NeedTranslation", "Translated", "InProgress" ], "x-ms-enum": { "name": "TranslationOption", "modelAsString": true } }, "CategoryContentResponse": { "required": [ "created_at", "enable_rtl", "hidden", "id", "is_fallback_content", "latest_version", "modified_at", "public_version", "status", "title", "version_number" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the category.", "format": "uuid", "nullable": true, "readOnly": true, "example": "9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d" }, "title": { "type": "string", "description": "Title of the category.", "nullable": true }, "content": { "type": "string", "description": "Markdown content of the category.", "nullable": true }, "html_content": { "type": "string", "description": "HTML-rendered content of the category.", "nullable": true }, "parent_category_id": { "type": "string", "description": "Identifier of the parent category, if any. Retrieve category IDs from `GET /v3/projects/{projectId}/workspaces/{workspaceId}/categories`.", "nullable": true }, "workspace_id": { "type": "string", "description": "Workspace this category belongs to. Corresponds to a workspace from `GET /v3/projects/{projectId}/workspaces`.", "nullable": true }, "version_number": { "type": "integer", "description": "Current version number of the content.", "format": "int32" }, "public_version": { "type": "integer", "description": "Published version number.", "format": "int32", "readOnly": true }, "latest_version": { "type": "integer", "description": "Latest available version number.", "format": "int32", "readOnly": true }, "enable_rtl": { "type": "boolean", "description": "Whether right-to-left text direction is enabled." }, "hidden": { "type": "boolean", "description": "Whether the category is hidden from readers." }, "status": { "enum": [ "draft", "published", "unpublished" ], "type": "string", "allOf": [ { "$ref": "#/components/schemas/ArticleStatus" } ], "description": "Publication status of the category.", "x-enumNames": [ "Draft", "Published", "Unpublished" ], "x-enum-varnames": [ "Draft", "Published", "Unpublished" ], "x-ms-enum": { "name": "ArticleStatus", "modelAsString": true } }, "version_type": { "type": "string", "description": "Derived version discriminator (version-less collab): `draft`, `published`, or `system_backup`. Null when collaborative editing is not enabled for the project. Display/system-backup ordinals are exposed only by the versions-list endpoint (they are relative to the full version set).", "nullable": true, "readOnly": true, "example": "draft" }, "created_by": { "type": "string", "description": "User ID of the creator. Corresponds to a user from `GET /v3/projects/{projectId}/users`.", "nullable": true }, "created_at": { "type": "string", "description": "Date and time the category was created. When you get or fork a specific category version, this is the date and time that version was created.", "format": "date-time", "readOnly": true }, "modified_at": { "type": "string", "description": "Date and time the category was last modified.", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "description": "User ID of who last modified this category. Corresponds to a user from `GET /v3/projects/{projectId}/users`.", "nullable": true, "readOnly": true }, "slug": { "type": "string", "description": "URL-friendly slug for the category.", "nullable": true, "readOnly": true }, "is_fallback_content": { "type": "boolean", "description": "Whether the content is a fallback from the default language." }, "content_type": { "allOf": [ { "$ref": "#/components/schemas/ContentType" } ], "description": "Content format type.", "nullable": true }, "current_workflow_status_id": { "type": "string", "description": "Current workflow status identifier, if workflows are enabled. Retrieve available statuses from `GET /v3/projects/{projectId}/workflow-statuses`.", "nullable": true }, "stale_status": { "allOf": [ { "$ref": "#/components/schemas/StaleStatusResponse" } ], "description": "The content freshness status of the page category: whether it is up to date or due for review, along with the review schedule. Mirrors the `stale_status` exposed by the article endpoints.", "nullable": true }, "content_hash": { "type": "string", "description": "SHA-256 hash of this version's stored content, prefixed with the algorithm\r\n(`sha256:`). Changes only when the content itself changes — record it at write\r\ntime and compare against later reads to detect drift without downloading content.\r\n`null` for versions saved before hash tracking was introduced.", "nullable": true, "readOnly": true, "example": "sha256:9f2c5a1d8e3b4c6f7a0918273645dacb5e1f2a3b4c5d6e7f8091a2b3c4d5e6f7" }, "custom_fields_data": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Read-only map of custom field name → display value for this page category (dropdown /\r\nmulti-select values are resolved to option labels; unset fields are `null`).\r\nPopulated on the category-content and category-version GET endpoints only. Named to match\r\nthe V1/V2 `customFieldsData` map, and kept distinct from the `custom_fields` array\r\non the settings endpoints, which is where raw values are read and written.", "nullable": true, "readOnly": true } }, "additionalProperties": false, "description": "Category content with versioning details." }, "ApiError": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "minLength": 1, "enum": [ "ACCESS_DENIED", "ARCHIVED_CONTENT_READ_ONLY", "ARCHIVE_ALREADY_ARCHIVED", "ARCHIVE_NOT_ARCHIVED", "BAD_REQUEST", "CONFLICT", "FEATURE_NOT_IN_LICENSE", "FEEDBACK_CLOSED", "FORBIDDEN", "INTERNAL_SERVER_ERROR", "LICENSE_LIMIT_EXCEEDED", "OPERATION_FAILED", "PERMISSION_DENIED", "PREMIUM_FEATURE_NOT_IN_LICENSE", "RESOURCE_NOT_FOUND", "TOO_MANY_REQUESTS", "UNAUTHORIZED", "UNRECOGNIZED_FIELD", "UNRECOGNIZED_FIELDS", "VALIDATION_ERROR" ], "type": "string", "description": "Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND)." }, "message": { "minLength": 1, "type": "string", "description": "Human-readable error message." }, "field": { "type": "string", "description": "The request field that caused the error, if applicable.", "nullable": true }, "details": { "type": "string", "description": "Additional context about the error.", "nullable": true } }, "additionalProperties": false, "description": "Represents an error returned by the API." }, "ApiWarning": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "minLength": 1, "type": "string", "description": "Machine-readable warning code." }, "message": { "minLength": 1, "type": "string", "description": "Human-readable warning message." } }, "additionalProperties": false, "description": "Represents a non-fatal warning from the API." }, "ArticleStatus": { "enum": [ "draft", "published", "unpublished" ], "type": "string", "description": "The publication status of an article.", "x-enumNames": [ "Draft", "Published", "Unpublished" ], "x-enum-varnames": [ "Draft", "Published", "Unpublished" ], "x-ms-enum": { "name": "ArticleStatus", "modelAsString": true } }, "StaleStatusResponse": { "required": [ "expire_days", "is_from_document_settings" ], "type": "object", "properties": { "article_stale_status": { "enum": [ "fresh", "stale" ], "type": "string", "allOf": [ { "$ref": "#/components/schemas/ArticleStaleStatus" } ], "description": "Whether the article is up to date (fresh) or requires review (stale).", "x-enumNames": [ "Fresh", "Stale" ], "x-enum-varnames": [ "Fresh", "Stale" ], "x-ms-enum": { "name": "ArticleStaleStatus", "modelAsString": true } }, "stale_reason": { "type": "string", "description": "The reason the article was marked stale, if any.", "nullable": true }, "expired_at": { "type": "string", "description": "The date the article is next due for review (UTC). Once this date passes, the article is considered stale.", "format": "date-time", "nullable": true, "example": "2026-01-31T05:10:26Z" }, "is_from_document_settings": { "type": "boolean", "description": "Whether the review schedule was inherited from project-level documentation settings.", "example": false }, "expire_days": { "type": "integer", "description": "The number of days from publication after which the article should next be reviewed.", "format": "int32", "example": 30 } }, "additionalProperties": false, "description": "Content freshness information for an article, derived from its review reminder schedule." }, "ArticleStaleStatus": { "enum": [ "fresh", "stale" ], "type": "string", "description": "The content freshness classification of an article, derived from its review reminder schedule.", "x-enumNames": [ "Fresh", "Stale" ], "x-enum-varnames": [ "Fresh", "Stale" ], "x-ms-enum": { "name": "ArticleStaleStatus", "modelAsString": true } } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "description": "API key for machine-to-machine integrations, webhooks, and CI/CD (recommended). This is a static, pre-shared secret - treat it as an opaque string and do not parse it; it is an API key, not an OAuth 2.0 access token. Create one in the portal under **Settings > Knowledge base portal > API keys** using the **Create API key** button - this is a different credential from the V1/V2 *API token*, which lives on its own screen and will not authenticate a V3 request. The plaintext key (format `d360_sk_...`) is shown only once, at creation. Send it in the `X-API-Key` header: `X-API-Key: d360_sk_...`. Each key carries a fixed portal role, content role, and content-access scope, supports an optional expiry, and can be disabled or deleted at any time from the portal.", "name": "X-API-Key", "in": "header" }, "Bearer": { "type": "oauth2", "description": "All V3 endpoints require a Bearer token. Generate tokens in the Document360 portal under **Settings > API Tokens**. Tokens are project-scoped, require the `customerApi` scope, and do not expire by default. Tokens can be revoked at any time from the portal. Include the token in every request: `Authorization: Bearer `. Alternatively, use the Authorize button below to sign in via OAuth2 Authorization Code flow with PKCE.", "flows": { "authorizationCode": { "authorizationUrl": "https://identity.document360.io/connect/authorize", "tokenUrl": "https://identity.document360.io/connect/token", "scopes": { "openid": "OpenID Connect", "profile": "User profile", "email": "User email", "customerApi": "Document360 Customer API" }, "x-usePkce": { "disableManualConfiguration": true, "hideClientSecretInput": true } } }, "x-d360-clientId": "apiHubWebClient" } } } } ````