{"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}/articles/{article_id}/comments":{"get":{"tags":["Articles > Comments"],"summary":"List comments on an article.","description":"Returns the comment threads on an article in a single resolution status (defaults to `open`),\r\nnewest first. Each comment's `id` matches the `data-comment-id` attribute of its marker in\r\nthe content returned by `GET /v3/projects/{projectId}/articles/{articleId}?content_mode=raw`, so a\r\nconsumer editing the content can re-associate a thread with the exact text it annotates. Use\r\n`commented_text` to read the annotated text directly, without searching the content yourself.\r\n \r\nThe list is cursor-paginated by modification time: pass the response's `next_cursor` back as\r\n`cursor` to fetch the next (older) page. `total_count` is populated on the first page only.\r\n \r\n**Access:** requires the `articles.update` permission, passes the same node-level ACL as the\r\narticle itself, and requires a resolvable user identity — a machine-to-machine token with no acting\r\nuser is rejected with `422`.\n\n### Related endpoints\n\n**Next**\n- `POST /v3/projects/{project_id}/articles/{article_id}/comments` — Starts a new thread on this article.\n- `PATCH /v3/projects/{project_id}/articles/{article_id}/comments/{comment_id}` — Resolves, reopens, or edits one of the threads returned here.\n\n**See also**\n- `GET /v3/projects/{project_id}/articles/{article_id}` — Reads the article content the comment markers live in. Each comment's `id` is the `data-comment-id` of its marker, so fetch with `content_mode=raw` to line them up.","operationId":"getArticleComments","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/ArticleId"},{"$ref":"#/components/parameters/LangCode"},{"name":"status","in":"query","description":"Resolution status to filter by: `open` (default), `resolved`, or `reopened`.","schema":{"enum":["open","resolved","reopened"],"type":"string","allOf":[{"$ref":"#/components/schemas/CommentStatus"}],"description":"Resolution status of an inline comment thread.","default":"open","x-enumNames":["Open","Resolved","Reopened"],"x-enum-varnames":["Open","Resolved","Reopened"],"x-ms-enum":{"name":"CommentStatus","modelAsString":true}}},{"$ref":"#/components/parameters/PageSize"},{"name":"cursor","in":"query","description":"Opaque cursor from a previous response's `next_cursor`. When provided, returns the page of comments following it.","schema":{"type":"string","example":"eyJpZCI6IjlhM2I0YzVkLTZlN2YtOGE5Yi0wYzFkLTJlM2Y0YTViNmM3ZCJ9"},"example":"eyJpZCI6IjlhM2I0YzVkLTZlN2YtOGE5Yi0wYzFkLTJlM2Y0YTViNmM3ZCJ9"}],"responses":{"200":{"description":"Comments retrieved 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/CommentListResponseApiResponse"},"examples":{"Open comments on an article":{"summary":"Two open threads: a text-anchored comment with one reply, and a block-anchored comment on a table. `next_cursor` is null because the page is not full.","value":{"data":{"total_count":2,"can_resolve_comments":true,"comments":[{"id":"3f8b1c22-9d4e-4a71-8c65-1b2a3c4d5e6f","title":"Clarify the prerequisite","comment":"

Can we state which plan this requires?

","commented_text":"This feature is available on all paid plans","commented_text_truncated":false,"status":"open","author_user_id":"7c1e4d90-2a3b-4c5d-8e9f-0a1b2c3d4e5f","resolved_by_user_id":null,"mentioned_user_ids":["9b2c3d4e-5f6a-4b8c-9d0e-1f2a3b4c5d6e"],"replies":[{"id":"5a6b7c8d-9e0f-4a1b-2c3d-4e5f6a7b8c9d","comment":"

Business plan and above — I'll add a note.

","author_user_id":"9b2c3d4e-5f6a-4b8c-9d0e-1f2a3b4c5d6e","mentioned_user_ids":[],"created_at":"2026-07-02T09:15:00Z","modified_at":"2026-07-02T09:15:00Z"}],"replies_count":1,"created_at":"2026-07-01T14:30:00Z","modified_at":"2026-07-02T09:15:00Z"},{"id":"8d7c6b5a-4f3e-42d1-b0a9-8c7d6e5f4a3b","title":"Table needs a units column","comment":"

Add a units column to this table.

","commented_text":null,"commented_text_truncated":false,"status":"open","author_user_id":"9b2c3d4e-5f6a-4b8c-9d0e-1f2a3b4c5d6e","resolved_by_user_id":null,"mentioned_user_ids":[],"replies":[],"replies_count":0,"created_at":"2026-06-28T11:05:00Z","modified_at":"2026-06-28T11:05:00Z"}],"next_cursor":null},"success":true,"request_id":"0HNNG2FP7GHU5:00000003","errors":null,"warnings":null}},"Resolved comments, more pages available":{"summary":"A full page of resolved threads. Pass `next_cursor` back as `cursor` to fetch the next (older) page. `total_count` is populated only on the first page.","value":{"data":{"total_count":47,"can_resolve_comments":false,"comments":[{"id":"1a2b3c4d-5e6f-4708-9a0b-1c2d3e4f5a6b","title":"Typo in the second paragraph","comment":"

"recieve" should be "receive".

","commented_text":"readers will recieve a notification","commented_text_truncated":false,"status":"resolved","author_user_id":"7c1e4d90-2a3b-4c5d-8e9f-0a1b2c3d4e5f","resolved_by_user_id":"9b2c3d4e-5f6a-4b8c-9d0e-1f2a3b4c5d6e","mentioned_user_ids":[],"replies":[],"replies_count":0,"created_at":"2026-06-21T10:00:00Z","modified_at":"2026-06-22T16:45:00Z"},{"id":"2b3c4d5e-6f7a-4819-8b0c-2d3e4f5a6b7c","title":null,"comment":"

The screenshot is stale — replaced with the 12.6 UI.

","commented_text":"the Settings page","commented_text_truncated":false,"status":"resolved","author_user_id":"9b2c3d4e-5f6a-4b8c-9d0e-1f2a3b4c5d6e","resolved_by_user_id":"7c1e4d90-2a3b-4c5d-8e9f-0a1b2c3d4e5f","mentioned_user_ids":[],"replies":[],"replies_count":0,"created_at":"2026-06-20T08:00:00Z","modified_at":"2026-06-20T08:00:00Z"}],"next_cursor":"MjAyNi0wNi0yMFQwODowMDowMC4wMDAwMDAwWnwyYjNjNGQ1ZS02ZjdhLTQ4MTktOGIwYy0yZDNlNGY1YTZiN2M="},"success":true,"request_id":"0HNNG2FP7GHU5:00000007","errors":null,"warnings":null}}}}},"links":{"createArticleComment":{"operationId":"createArticleComment","description":"Starts a new thread on this article."},"updateArticleComment":{"operationId":"updateArticleComment","description":"Resolves, reopens, or edits one of the threads returned here."}}},"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":"The role does not grant `articles.update`, or node-level access to the article is denied.","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":"Article 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}}}}}},"422":{"description":"No user identity could be resolved (machine-to-machine token without an acting user), or `status` or `cursor` is not a valid value.","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}}}}}},"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}/articles/{article_id}","operationId":"getArticle","description":"Reads the article content the comment markers live in. Each comment's `id` is the `data-comment-id` of its marker, so fetch with `content_mode=raw` to line them up."},{"relationship":"next","method":"POST","path":"/v3/projects/{project_id}/articles/{article_id}/comments","operationId":"createArticleComment","description":"Starts a new thread on this article."},{"relationship":"next","method":"PATCH","path":"/v3/projects/{project_id}/articles/{article_id}/comments/{comment_id}","operationId":"updateArticleComment","description":"Resolves, reopens, or edits one of the threads returned here."}]}}},"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"}},"ArticleId":{"name":"article_id","in":"path","description":"The unique identifier of the article. Retrieve article IDs from `GET /v3/projects/{projectId}/articles`.","required":true,"schema":{"type":"string","format":"uuid","example":"9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d"}},"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"}},"PageSize":{"name":"page_size","in":"query","description":"Number of results per page. Defaults to 25. Maximum 100.","schema":{"maximum":100,"minimum":1,"type":"integer","format":"int32","default":25}}},"schemas":{"CommentStatus":{"enum":["open","resolved","reopened"],"type":"string","description":"Resolution status of an inline comment thread.","x-enumNames":["Open","Resolved","Reopened"],"x-enum-varnames":["Open","Resolved","Reopened"],"x-ms-enum":{"name":"CommentStatus","modelAsString":true}},"CommentListResponseApiResponse":{"required":["data","request_id","success"],"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/CommentListResponse"}],"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"},"CommentListResponse":{"required":["can_resolve_comments"],"type":"object","properties":{"total_count":{"type":"integer","description":"Total number of comments matching the requested status. Populated on the first page only (when no\r\n`cursor` is supplied) because counting is a full scan of the match; `null` on cursor\r\npages — distinct from `0`, which means the document genuinely has no comments in this status.","format":"int32","nullable":true},"can_resolve_comments":{"type":"boolean","description":"Whether the acting user is permitted to change the resolution status of comments on this\r\narticle/category."},"comments":{"type":"array","items":{"$ref":"#/components/schemas/CommentResponse"},"description":"The comments on this page, newest first.","nullable":true},"next_cursor":{"type":"string","description":"Opaque cursor for the next page: pass it back as `cursor` to fetch the following (older)\r\ncomments. `null` when this is the last page. Treat the value as opaque — its format is not\r\npart of the contract.","nullable":true,"readOnly":true,"example":"MjAyNi0wNi0yMFQwODowMDowMC4wMDAwMDAwWnwyYjNjNGQ1ZS02ZjdhLTQ4MTktOGIwYy0yZDNlNGY1YTZiN2M="}},"additionalProperties":false,"description":"A page of inline comments for an article or category, in a single resolution status."},"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."},"CommentResponse":{"required":["commented_text_truncated","created_at","id","modified_at","replies_count","status","title"],"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the comment thread, and the value carried by the comment's marker in the content\r\nas `data-comment-id`.\r\n\n\r\nDo not rely on finding it in a `content_mode=raw` response. Raw mode returns the DFM markdown\r\nrepresentation, and a `` marker does not survive the conversion into it — only the\r\nEditor 3.0 `` form passes through. Use Document360.Customer.API.Models.V3.CommentResponse.CommentedText to learn what a\r\ncomment annotates rather than searching the content yourself.\r\n","format":"uuid","nullable":true,"readOnly":true,"example":"9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d"},"title":{"type":"string","description":"Optional title/summary of the comment thread.","nullable":true},"comment":{"type":"string","description":"The comment body (sanitized HTML).","nullable":true},"commented_text":{"type":"string","description":"The text in the document that this comment annotates — the content inside its highlight marker — as\r\nplain text.\r\n\n\r\nRead from the document's current content on every request rather than stored with the comment, so it\r\nalways reflects what the text says now. A consequence worth knowing: edit the annotated sentence and\r\nthis value changes; it is not a record of what the text said when the comment was written.\r\n\n\r\nFor an Editor 3.0 comment anchored outside the content (a standoff `anchor`), there is no marker;\r\nthe value is then the anchor's quoted text as captured when the comment was written. A marker, when\r\npresent, always takes precedence.\r\n\n`null` when the annotated text cannot be determined, which is an ordinary outcome and not an\r\nerror — the marker was removed (the thread is orphaned and now annotates nothing), the document is\r\nstored in a form this cannot read, or the comment predates the marker convention. Treat it as\r\n\"unknown\", and do not assume a comment with `null` here is invalid.\r\n\n\r\nA comment may annotate a selection spanning several paragraphs; those fragments are joined with single\r\nspaces, and runs of whitespace from the document's own markup are collapsed. Long selections are\r\ntruncated — see Document360.Customer.API.Models.V3.CommentResponse.CommentedTextTruncated.\r\n","nullable":true,"readOnly":true,"example":"single sign-on"},"commented_text_truncated":{"type":"boolean","description":"Whether Document360.Customer.API.Models.V3.CommentResponse.CommentedText was cut short because the annotated selection exceeded the\r\nresponse limit. When `true`, the value is a prefix of the real annotated text, not the whole of\r\nit — fetch the document content if the full span matters.","readOnly":true},"status":{"enum":["open","resolved","reopened"],"type":"string","allOf":[{"$ref":"#/components/schemas/CommentStatus"}],"description":"Resolution status of the thread.","x-enumNames":["Open","Resolved","Reopened"],"x-enum-varnames":["Open","Resolved","Reopened"],"x-ms-enum":{"name":"CommentStatus","modelAsString":true}},"author_user_id":{"type":"string","description":"Identifier of the team account that created the comment.","nullable":true},"resolved_by_user_id":{"type":"string","description":"Identifier of the team account that resolved the thread. `null` when still open.","nullable":true},"mentioned_user_ids":{"type":"array","items":{"type":"string"},"description":"Identifiers of team accounts @-mentioned in the comment.","nullable":true},"replies":{"type":"array","items":{"$ref":"#/components/schemas/CommentReplyResponse"},"description":"Replies on this comment thread.","nullable":true},"replies_count":{"type":"integer","description":"Total number of replies on the thread.","format":"int32"},"created_at":{"type":"string","description":"UTC timestamp when the comment was created.","format":"date-time","readOnly":true},"modified_at":{"type":"string","description":"UTC timestamp when the comment was last modified.","format":"date-time","readOnly":true}},"additionalProperties":false,"description":"A single inline comment thread left on an article or category by an author/reviewer, together with its\r\nreplies. The `id` matches the `data-comment-id` attribute of the comment's marker in the\r\ncontent, so a consumer editing the content can re-associate a comment with the exact text it annotates.\r\n\n\r\nTwo marker forms exist, and both are valid — which one a document uses depends on the editor that wrote\r\nit: `` for block (Advanced WYSIWYG) content, and\r\n`` for Editor 3.0. Match on the attribute\r\nrather than on the element name.\r\n"},"CommentReplyResponse":{"required":["created_at","id","modified_at"],"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the reply.","format":"uuid","nullable":true,"readOnly":true,"example":"9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d"},"comment":{"type":"string","description":"The reply body (sanitized HTML).","nullable":true},"author_user_id":{"type":"string","description":"Identifier of the team account that created the reply.","nullable":true},"mentioned_user_ids":{"type":"array","items":{"type":"string"},"description":"Identifiers of team accounts @-mentioned in the reply.","nullable":true},"created_at":{"type":"string","description":"UTC timestamp when the reply was created.","format":"date-time","readOnly":true},"modified_at":{"type":"string","description":"UTC timestamp when the reply was last modified.","format":"date-time","readOnly":true}},"additionalProperties":false,"description":"A reply within an inline comment thread."}},"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"}}}}