{"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\nEvery request must include your API token in the `api_token` header. Generate tokens in the Document360 portal under **Settings → Knowledge base portal → API tokens**. Tokens are project-scoped and can be revoked at any time. The same token can be passed via the `api_token` query string for situations where headers are not configurable, but the header form is strongly preferred.\n\n## Project context\nMany endpoints implicitly resolve the project from the API token. When an endpoint requires explicit project context, pass the project identifier in the `ProjectId` header.\n\n## Identifiers — how to fetch them\nMost endpoints accept one or more identifiers as path, query, or body parameters. Use the discovery endpoints below to look them up programmatically rather than hard-coding values:\n\n| Identifier | What it is | Where to fetch it |\n| --- | --- | --- |\n| `projectVersionId` (a.k.a. workspaceId) | A workspace/version inside the project — content (articles, categories, languages) lives within one. | `GET /v2/projectversions` — returns all workspaces with their `id`. Required first to discover articles, categories, and languages. |\n| `categoryId` | A category in the category tree. | `GET /v2/projectversions/{projectVersionId}/categories` — returns the full category hierarchy with each category's `id`. |\n| `articleId` | An article inside a category. | `GET /v2/projectversions/{projectVersionId}/articles` — lists all articles in the workspace. Also available inside the categories tree response. |\n| `langCode` | Two-letter / locale code (`en`, `fr`, `de-DE`, `pt-BR`, …) of an article or category translation. | `GET /v2/language/{projectVersionId}` — returns the languages enabled for the workspace, including `code` and `name`. |\n| `versionNumber` | A specific version of an article or category translation. | `GET /v2/articles/{articleId}/{langCode}/versions` for articles, `GET /v2/categories/{categoryId}/{langCode}versions` for categories. |\n| `userId` (team account) | A portal user (team member). | `GET /v2/teams` — lists all team accounts with their `userId`. `GET /v2/teams/{userId}` returns full details for one. |\n| `groupId` (team) | A team account group. | `GET /v2/teams/groups`. |\n| `roleId` | A role assignable to team accounts. | `GET /v2/teams/roles`. |\n| `readerId` | A reader account (used for private docs / reader analytics). | `GET /v2/readers` — supports pagination and `searchEmail` filtering. |\n| `groupId` (reader) | A reader group. | `GET /v2/readers/groups`. |\n\n**Tip:** In the Document360 portal, the article and category IDs are visible in the URL when an item is open in the editor — e.g. `…/docs//edit/`. `projectId` and `projectVersionId` are visible in **Settings → API tokens** and **Documentation → Workspaces** respectively.\n\n## Query parameter casing\nV1/V2 query parameters use **snake_case** on the wire (for example `search_email`, `exclude_readers`, `version_number`). The server transparently maps snake_case query keys to the camelCase parameter names you see in this specification, so either casing is accepted, but snake_case is the documented convention for V1/V2.\n\n## Response envelope\nAll responses are wrapped in a consistent envelope:\n\n- `success` (boolean) — `true` when the operation succeeded, `false` otherwise. Always check this before reading the payload.\n- `errors` (array) — populated when `success` is `false`. Each entry has a human-readable `description`.\n- `warnings` / `information` (arrays) — non-fatal advisories returned alongside a successful response.\n- `result` or `data` — the operation's payload (the property name depends on the endpoint).\n\nHTTP status codes follow standard semantics (`200` success, `400` validation/business error, `401` missing or invalid token, `403` plan/permission restriction, `404` not found, `429` rate-limited, `5xx` server error). For non-`200` responses the envelope still applies — inspect `errors[].description` for details.\n\n## Rate limits\nEndpoints are rate-limited per API token per project. When throttled, the server returns `429 Too Many Requests` along with `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. Use exponential backoff with jitter and respect the `Retry-After` header on the response.\n\n## Versioning\nAll routes are prefixed with the API version: `/v1/...` and `/v2/...`. V1 and V2 are stable; V3 is in Beta. New endpoints and fields may be added without notice in V1/V2 — they will never be removed or renamed in a backwards-incompatible way.","version":"2.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"}}}],"tags":[{"name":"Articles","description":"Create, read, update, publish, fork, and delete knowledge base articles. Manage article versions, settings, descriptions, workflow status, and bulk operations. Supports both Markdown and WYSIWYG/Block content types."},{"name":"Categories","description":"Manage the category hierarchy that organizes articles. Create, update, reorder, and delete categories; manage category content, settings, workflow status, and bulk operations."},{"name":"Drive","description":"Upload, organize, and manage media files and folders in Drive (used in articles and documentation)."},{"name":"Readers","description":"Manage reader accounts and reader groups for private documentation. Create readers, assign them to groups, and manage access scopes."},{"name":"Teams","description":"Manage team accounts (portal users), team groups, and role assignments within a project."},{"name":"Project","description":"Project-level operations: export and import project documentation as zip archives."},{"name":"ProjectVersions","description":"Manage workspaces (also called project versions) within a project. List, search, fetch settings, and inspect version metadata."},{"name":"Language","description":"Retrieve languages configured for a workspace."},{"name":"Translations","description":"Query article translation status across the configured languages."},{"name":"CustomField","description":"Retrieve custom field definitions configured for the project. Custom field values are written/read via the Article and Category settings endpoints."},{"name":"APIReferences","description":"Import OpenAPI/Swagger specifications into API reference documentation and inspect import logs."}],"x-tagGroups":[{"name":"Workspace","tags":["Project","ProjectVersions"]},{"name":"Content","tags":["Articles","Categories"]},{"name":"Media","tags":["Drive"]},{"name":"Access","tags":["Readers","Teams"]},{"name":"Localization","tags":["Language","Translations"]},{"name":"Custom data","tags":["CustomField"]}],"paths":{"/v2/Articles":{"post":{"tags":["Articles"],"summary":"Adds an article to an existing category","description":"Creates a new article under the specified category in the workspace's default language. The returned `data.id` is the new article's `articleId` to use in subsequent calls.\r\nThe slug is auto-generated from the title unless an explicit `slug` is supplied; explicit slugs must be unique within the workspace.\r\n**Not idempotent** — retrying after a 5xx can create duplicates. Before retrying, list articles in the target category (`GET /v2/projectversions/{projectVersionId}/articles`) and check whether your new article already exists.","operationId":"createArticle","requestBody":{"description":"The article creation payload. The `categoryId` field is required (fetch via `GET /v2/projectversions/{projectVersionId}/categories`). When `contentType` is omitted, the project's default content type is used.","content":{"application/json-patch+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CreateArticleRequest"}]},"examples":{"Minimal — Markdown article":{"summary":"The smallest viable payload: title, content, and the destination category. The slug is auto-generated from the title; `contentType` defaults to the project's default editor.","value":{"title":"Getting started with our SDK","content":"## Install\n\n`npm install @example/sdk`\n\n## Initialize\n\n```js\nconst client = new Client({ apiKey: 'YOUR_KEY' });\n```","category_id":"5b291e6b-fa40-4ab9-941e-f8fffc23b376","project_version_id":"46f48bc7-760f-4b07-b2d2-fce4aa8ba234","order":0,"user_id":"f11efc6f-e968-4e95-82eb-85ad61559de8","content_type":null,"editor_version":null,"slug":null}},"Block-editor article with explicit slug":{"summary":"Create a Block-editor article with a custom slug and ordering. `contentType` is set explicitly to override the project default; `slug` must be unique within the workspace.","value":{"title":"Configure single sign-on with Okta","content":"{\"blocks\":[{\"type\":\"heading\",\"data\":{\"level\":2,\"text\":\"Prerequisites\"}},{\"type\":\"paragraph\",\"data\":{\"text\":\"You need an Okta admin account…\"}}]}","category_id":"5b291e6b-fa40-4ab9-941e-f8fffc23b376","project_version_id":"46f48bc7-760f-4b07-b2d2-fce4aa8ba234","order":5,"user_id":"f11efc6f-e968-4e95-82eb-85ad61559de8","content_type":2,"editor_version":null,"slug":"configure-single-sign-on-with-okta"}},"Editor 3.0 (Beta) article":{"summary":"Opt the new article into Editor 3.0 (Beta) via `editorVersion`. Honoured only when the project is enabled for the Editor 3.0 beta; otherwise the request is rejected. Created as a Block-editor article.","value":{"title":"Try the new editor","content":"{\"blocks\":[{\"type\":\"paragraph\",\"data\":{\"text\":\"Authored in Editor 3.0.\"}}]}","category_id":"5b291e6b-fa40-4ab9-941e-f8fffc23b376","project_version_id":"46f48bc7-760f-4b07-b2d2-fce4aa8ba234","order":0,"user_id":"f11efc6f-e968-4e95-82eb-85ad61559de8","content_type":2,"editor_version":3,"slug":null}},"WYSIWYG (HTML) article":{"summary":"Create a WYSIWYG article. The `content` field carries HTML directly.","value":{"title":"Release notes — Q4","content":"

This release introduces…

","category_id":"5b291e6b-fa40-4ab9-941e-f8fffc23b376","project_version_id":"46f48bc7-760f-4b07-b2d2-fce4aa8ba234","order":0,"user_id":"f11efc6f-e968-4e95-82eb-85ad61559de8","content_type":1,"editor_version":null,"slug":null}}}}},"required":true},"responses":{"200":{"description":"Operation succeeded. Inspect the response envelope's `success` flag and the `result`/`data` payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateArticleResponse"},"examples":{"Article Created Successfully":{"summary":"The article has been created under the following category. you can use the article Id to view the article in the portal.","value":{"data":{"id":"925b69b9-f241-4d89-9e3e-208a98dfc8eb","title":"Sample Article","public_version":0,"latest_version":1,"language_code":null,"hidden":false,"status":0,"order":3,"slug":"sample-article","content_type":null,"translation_option":0,"is_shared_article":false,"created_at":null,"modified_at":null,"current_workflow_status_id":null},"extension_data":null,"success":true,"errors":[],"warnings":[],"information":[]}}}}}},"400":{"description":"The request body or query parameters failed validation. Inspect `errors[].description` for the offending fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerApiBaseResponse"},"examples":{"userId not found":{"summary":"Kindly check your user Id and perform the task again. Find your user Id at /v2/Teams.","value":{"extension_data":null,"success":false,"errors":[{"extension_data":null,"stack_trace":null,"description":"The user with id 'f11efc6f-e968-4e95-82eb-85ad61559de81' does not exist in your project.","error_code":"400","custom_data":null}],"warnings":[],"information":[]}},"category_id not found":{"summary":"Kindly check the category_id from /v2/ProjectVersions/{projectVersionId}/categories and perform the task again.","value":{"extension_data":null,"success":false,"errors":[{"extension_data":null,"stack_trace":null,"description":"Unable to find specified parent category with an id 5b291e6b-fa40-4ab9-941e-f8fffc23b3761.","error_code":"400","custom_data":null}],"warnings":[],"information":[]}},"project_version_id not found":{"summary":"Kindly check the project_version_id from /v2/ProjectVersions and perform the task again.","value":{"extension_data":null,"success":false,"errors":[{"extension_data":null,"stack_trace":null,"description":"The supplied project version id 46f48bc7-760f-4b07-b2d2-fce4aa8ba2349 does not exist in your project.","error_code":"400","custom_data":null}],"warnings":[],"information":[]}},"title not found":{"summary":"Kindly check the title is empty or null, and perform the task again.","value":{"extension_data":null,"success":false,"errors":[{"extension_data":null,"stack_trace":null,"description":"The Title field is required.","error_code":"400","custom_data":null}],"warnings":[],"information":[]}}}}}},"401":{"description":"Authentication failed — the `api_token` header is missing, malformed, or has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerApiBaseResponse"}}}},"429":{"description":"Rate limit exceeded for this api_token. Wait for the duration in the `Retry-After` header before retrying.","headers":{"Retry-After":{"description":"Number of seconds to wait before retrying the request.","schema":{"type":"integer","format":"int32"}},"X-RateLimit-Limit":{"description":"The maximum number of requests allowed in the current window.","schema":{"type":"integer","format":"int32"}},"X-RateLimit-Remaining":{"description":"The number of requests remaining in the current window.","schema":{"type":"integer","format":"int32"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the current rate-limit window resets.","schema":{"type":"integer","format":"int64"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerApiBaseResponse"}}}}},"security":[{"api_token":[]}]}}},"components":{"schemas":{"CreateArticleRequest":{"required":["project_version_id","title","user_id"],"type":"object","properties":{"title":{"minLength":1,"type":"string","description":"The title of the article"},"content":{"type":"string","description":"The content of the article, for any Editor type, use this property","nullable":true},"category_id":{"type":"string","description":"The ID of the category where the article will be created, CategoryId will be null for custom pages","nullable":true},"project_version_id":{"minLength":1,"type":"string","description":"The project version ID in which the article will be created"},"order":{"type":"integer","description":"The position of the article in the category tree (By default, it will be placed at the bottom of the category)","format":"int32"},"user_id":{"minLength":1,"type":"string","description":"The ID of the team account that will be marked as a contributor of the article"},"content_type":{"allOf":[{"$ref":"#/components/schemas/ArticleContentType"}],"description":"0 - Markdown; 1 - WYSIWYG(HTML); 2 - Advanced WYSIWYG","default":null,"nullable":true},"editor_version":{"allOf":[{"$ref":"#/components/schemas/EditorVersion"}],"description":"The editor to author the article in. 2 - classic editor; 3 - Editor 3.0. In projects where the\r\nEditor 3.0 flow is enabled, the article defaults to Editor 3.0 (3) when this is omitted; pass 2 for\r\nthe classic editor. In projects without the V3 flow, a value of 3 is rejected.","default":null,"nullable":true},"slug":{"type":"string","description":"Optional custom URL-friendly slug for the article. If not provided, a slug will be auto-generated from the title.\r\nWhen provided, the slug must be unique within the project version, otherwise an error will be returned.","nullable":true,"readOnly":true}},"additionalProperties":false},"CreateArticleResponse":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/ArticleSimpleDataCustomer"}],"description":"Create article response data","nullable":true},"extension_data":{"allOf":[{"$ref":"#/components/schemas/ExtensionDataObject"}],"description":"Extension data for customer API response","nullable":true},"success":{"type":"boolean","description":"Indicates the status of the API response. A value of true signifies that the request was successfully processed, while false indicates a failure or error occurred.","readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/BaseError"},"description":"A list of errors encountered during the API request. Each error object provides details about the problem, including an error code and a message explaining the issue. This field is populated when the request fails or encounters issues.","nullable":true},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/BaseWarning"},"description":"A list of warnings generated during the API request. These are non-critical issues or recommendations that might affect the request but won't stop it from processing. Each warning object provides a message to inform the user of potential problems.","nullable":true},"information":{"type":"array","items":{"$ref":"#/components/schemas/BaseInformation"},"description":"Contains additional non-critical information relevant to the request or response. This field provides extra details that might assist in understanding the context of the API response but is not essential for processing.","nullable":true}},"additionalProperties":false},"CustomerApiBaseResponse":{"type":"object","properties":{"extension_data":{"allOf":[{"$ref":"#/components/schemas/ExtensionDataObject"}],"description":"Extension data for customer API response","nullable":true},"success":{"type":"boolean","description":"Indicates the status of the API response. A value of true signifies that the request was successfully processed, while false indicates a failure or error occurred.","readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/BaseError"},"description":"A list of errors encountered during the API request. Each error object provides details about the problem, including an error code and a message explaining the issue. This field is populated when the request fails or encounters issues.","nullable":true},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/BaseWarning"},"description":"A list of warnings generated during the API request. These are non-critical issues or recommendations that might affect the request but won't stop it from processing. Each warning object provides a message to inform the user of potential problems.","nullable":true},"information":{"type":"array","items":{"$ref":"#/components/schemas/BaseInformation"},"description":"Contains additional non-critical information relevant to the request or response. This field provides extra details that might assist in understanding the context of the API response but is not essential for processing.","nullable":true}},"additionalProperties":false},"ArticleContentType":{"enum":["markdown","wysiwyg","block"],"type":"string","description":"0 - Markdown; 1 - WYSIWYG(HTML); 2 - Advanced WYSIWYG","x-enumNames":["Markdown","Wysiwyg","Block"],"x-enum-varnames":["Markdown","Wysiwyg","Block"],"x-ms-enum":{"name":"ArticleContentType","modelAsString":true}},"EditorVersion":{"enum":["v2","v3"],"type":"string","description":"Per-article editor version. Orthogonal to Document360.Core.Enums.ArticleContentType:\r\nit records which editor surface the article was authored in / should open in,\r\nnot the content format. Unset (null) means \"legacy\" — the editor falls back to\r\nthe project-version rollout decision. Values mirror the portal enum.\r\n2 - Editor 2.0 (existing); 3 - Editor 3.0 (TipTap 3.x).","x-enumNames":["V2","V3"],"x-enum-varnames":["V2","V3"],"x-ms-enum":{"name":"EditorVersion","modelAsString":true}},"ArticleSimpleDataCustomer":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the article","nullable":true,"readOnly":true},"title":{"type":"string","description":"The article title","nullable":true},"public_version":{"type":"integer","description":"The article version number(revision) that is currently published","format":"int32","readOnly":true},"latest_version":{"type":"integer","description":"The latest version number of this article","format":"int32","readOnly":true},"language_code":{"type":"string","description":"The default language code","nullable":true,"deprecated":true},"hidden":{"type":"boolean","description":"Indicates if the article is visible on the site"},"status":{"enum":["draft","published"],"type":"string","allOf":[{"$ref":"#/components/schemas/ArticleStatusCustomer"}],"description":"The status of the article: 0 - Draft, 3 - Published","x-enumNames":["Draft","Published"],"x-enum-varnames":["Draft","Published"],"x-ms-enum":{"name":"ArticleStatusCustomer","modelAsString":true}},"order":{"type":"integer","description":"The position of the article inside the parent category","format":"int32"},"slug":{"type":"string","description":"The slug of the article","nullable":true,"readOnly":true},"content_type":{"allOf":[{"$ref":"#/components/schemas/ArticleContentType"}],"description":"The content type of the article: Markdown = 0, Wysiwyg = 1, Block = 2","nullable":true},"translation_option":{"enum":["none","needTranslation","translated","inProgress"],"type":"string","allOf":[{"$ref":"#/components/schemas/LanguageTranslationOption"}],"description":"The translation status of the document.\r\nValid values: 0 - None, 1 - Need Translation, 2 - Translated, 3 - In Progress","x-enumNames":["None","NeedTranslation","Translated","InProgress"],"x-enum-varnames":["None","NeedTranslation","Translated","InProgress"],"x-ms-enum":{"name":"LanguageTranslationOption","modelAsString":true}},"is_shared_article":{"type":"boolean","description":"`True` indicates that the article is shared"},"created_at":{"type":"string","description":"Article created date time","format":"date-time","nullable":true,"readOnly":true},"modified_at":{"type":"string","description":"Article modified date time","format":"date-time","nullable":true,"readOnly":true},"current_workflow_status_id":{"type":"string","description":"Current Workflow status of the article","nullable":true}},"additionalProperties":false,"description":"Compact article representation — title, slug, current/latest version numbers, hierarchy position, and basic settings. Returned in list endpoints and create/bulk-create responses where the full content body is not required."},"ExtensionDataObject":{"type":"object","additionalProperties":false},"BaseError":{"type":"object","properties":{"extension_data":{"allOf":[{"$ref":"#/components/schemas/ExtensionDataObject"}],"description":"This is the Extension data object","nullable":true},"stack_trace":{"type":"string","description":"A technical trace showing where the error occurred within the system. Intended for backend debugging.","nullable":true},"description":{"type":"string","description":"A clear message explaining what caused the error. This helps quickly understand what went wrong.","nullable":true},"error_code":{"type":"string","description":"A short, predefined code that identifies the type of error. Useful for logging the error or raising a support request.","nullable":true},"custom_data":{"type":"object","additionalProperties":{},"description":"Any structured metadata for the error object.","nullable":true}},"additionalProperties":false,"description":"One structured error in a response's Document360.Core.Messages.Core.BaseResponse.errors array."},"BaseWarning":{"type":"object","properties":{"extension_data":{"allOf":[{"$ref":"#/components/schemas/ExtensionDataObject"}],"description":"Extension Data for customer Api warning","nullable":true},"description":{"type":"string","description":"A plain message that describes the warning and helps understand what should be reviewed.","nullable":true},"warning_code":{"type":"string","description":"A short, predefined code that uniquely identifies the warning type.","nullable":true}},"additionalProperties":false,"description":"One non-fatal warning attached to an otherwise-successful response."},"BaseInformation":{"type":"object","properties":{"extension_data":{"allOf":[{"$ref":"#/components/schemas/ExtensionDataObject"}],"description":"Extension data for customer Api response information","nullable":true},"description":{"type":"string","description":"A plain message offering helpful context about the response, such as confirmation of fallback logic or skipped operations.","nullable":true}},"additionalProperties":false,"description":"One informational message in a response's Document360.Core.Messages.Core.BaseResponse.information array. Non-error context the SPA may surface to the user."},"ArticleStatusCustomer":{"enum":["draft","published"],"type":"string","description":"The status of the article: 0 - Draft, 3 - Published","x-enumNames":["Draft","Published"],"x-enum-varnames":["Draft","Published"],"x-ms-enum":{"name":"ArticleStatusCustomer","modelAsString":true}},"LanguageTranslationOption":{"enum":["none","needTranslation","translated","inProgress"],"type":"string","description":"0 - None, 1 - Needs transation, 2 - Translated, 3 - In progress","x-enumNames":["None","NeedTranslation","Translated","InProgress"],"x-enum-varnames":["None","NeedTranslation","Translated","InProgress"],"x-ms-enum":{"name":"LanguageTranslationOption","modelAsString":true}}},"securitySchemes":{"api_token":{"type":"apiKey","description":"The API token used for authenticating the request. This must be passed as a header parameter. To generate an API token, go to **Settings > Knowledge base portal > API tokens**. This token must correspond to a valid workspace and permission level.","name":"api_token","in":"header"}}}}