{"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/Categories/{categoryId}/content/{langCode}":{"put":{"tags":["Categories"],"summary":"Updates a category page content with the ID","operationId":"updateCategoryContent","parameters":[{"name":"categoryId","in":"path","description":"The ID of the category. Fetch via `GET /v2/projectversions/{projectVersionId}/categories`.","required":true,"schema":{"type":"string"},"example":"de104b39-db97-4509-8d4c-deeac74d448b"},{"name":"langCode","in":"path","description":"Language code of the category translation (for example `en`, `fr`, `de-DE`, `pt-BR`). Use `GET /v2/language/{projectVersionId}` to list the codes enabled for a workspace. Defaults to `en` when omitted.","required":true,"schema":{"type":"string","default":"en"},"example":"en"}],"requestBody":{"description":"Partial content update payload — only the fields present in the request body are updated. Do not pass content fetched with `isForDisplay=true`; the resolved merge codes would overwrite the source.","content":{"application/json-patch+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/UpdateCategoryContentCustomerRequest"}]},"examples":{"Successfully Updated Category":{"summary":"Updated Catgory information is shown in this response.","value":{"title":"UpdateTitleForCategoryPage","content":"This is my updated content.","html_content":"

This is my updated content,

","block_content":"

This is my updated content,

","version_number":1,"translation_option":"","source":"","updated_by":"f11efc6f-e968-4e95-82eb-85ad61559de8"}}}},"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/UpdateCategoryContentCustomerRequest"}]},"examples":{"Successfully Updated Category":{"summary":"Updated Catgory information is shown in this response.","value":{"title":"UpdateTitleForCategoryPage","content":"This is my updated content.","html_content":"

This is my updated content,

","block_content":"

This is my updated content,

","version_number":1,"translation_option":"","source":"","updated_by":"f11efc6f-e968-4e95-82eb-85ad61559de8"}}}},"text/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/UpdateCategoryContentCustomerRequest"}]},"examples":{"Successfully Updated Category":{"summary":"Updated Catgory information is shown in this response.","value":{"title":"UpdateTitleForCategoryPage","content":"This is my updated content.","html_content":"

This is my updated content,

","block_content":"

This is my updated content,

","version_number":1,"translation_option":"","source":"","updated_by":"f11efc6f-e968-4e95-82eb-85ad61559de8"}}}},"application/*+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/UpdateCategoryContentCustomerRequest"}]},"examples":{"Successfully Updated Category":{"summary":"Updated Catgory information is shown in this response.","value":{"title":"UpdateTitleForCategoryPage","content":"This is my updated content.","html_content":"

This is my updated content,

","block_content":"

This is my updated content,

","version_number":1,"translation_option":"","source":"","updated_by":"f11efc6f-e968-4e95-82eb-85ad61559de8"}}}}},"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/UpdateCategoryContentCustomerResponse"},"examples":{"Successfully Updated Category":{"summary":"Updated Catgory information is shown in this response.","value":{"data":{"id":"d6f49c75-1eea-4101-bfd4-fd314f57815d","title":"UpdateTitleForCategoryPage","content":"This is my updated content.","html_content":"

This is my updated content.

\n","block_content":null,"category_id":"d6f49c75-1eea-4101-bfd4-fd314f57815d","project_version_id":"46f48bc7-760f-4b07-b2d2-fce4aa8ba234","version_number":2,"public_version":1,"latest_version":2,"enable_rtl":false,"hidden":false,"status":0,"version_type":null,"order":0,"created_by":"f11efc6f-e968-4e95-82eb-85ad61559de8","authors":[],"created_at":"2024-06-13T14:30:00","modified_at":"2024-06-13T14:30:00","slug":"updatetitleforcategorypage","is_fall_back_content":false},"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":{"Non-Empty body is required.":{"summary":"This response is due to an empty request body. \\n Kindly make some body parameters to get success response.","value":{"extension_data":null,"success":false,"errors":[{"extension_data":null,"stack_trace":null,"description":"A non-empty request body 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"}}}},"404":{"description":"The requested resource was not found, or the supplied identifier does not exist in the project.","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":{"UpdateCategoryContentCustomerRequest":{"type":"object","properties":{"title":{"type":"string","description":"The title of the category","nullable":true},"content":{"type":"string","description":"The content of the category, for any Editor type, use this property.","nullable":true},"html_content":{"type":"string","description":"The HTML content of the category. If the editor type is WYSIWYG (HTML), use this property - (This property is deprecated and will be removed in a future version of the API, Kindly use **content** property instead of this.)","nullable":true,"deprecated":true},"block_content":{"type":"string","description":"The HTML content of the category. If the editor type is Block Editor (HTML), use this property - (This property is deprecated and will be removed in a future version of the API, Kindly use **content** property instead of this.)","nullable":true,"deprecated":true},"version_number":{"type":"integer","description":"The version number of the category to be updated. The latest version is updated by default.","format":"int32","nullable":true},"translation_option":{"type":"string","description":"Translation status of the category. 0 - None, 1 - Needs translation, 2 Translated","nullable":true},"source":{"type":"string","description":"Free text used for future reference","nullable":true},"updated_by":{"type":"string","description":"The ID of the team account responsible for the category update","nullable":true}},"additionalProperties":false},"UpdateCategoryContentCustomerResponse":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/CategoryVersionDataCustomer"}],"description":"category version 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},"CategoryVersionDataCustomer":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the category","nullable":true,"readOnly":true},"title":{"type":"string","description":"The title of the category","nullable":true},"content":{"type":"string","description":"The content of the category","nullable":true},"html_content":{"type":"string","description":"The HTML content of the category","nullable":true},"block_content":{"type":"string","description":"The HTML content of the category (Block editor)","nullable":true},"category_id":{"type":"string","description":"Existing category ID","nullable":true},"project_version_id":{"type":"string","description":"Existing project version ID","nullable":true},"version_number":{"type":"integer","description":"Category Version Number","format":"int32"},"public_version":{"type":"integer","description":"The ID of the project version where this category is located","format":"int32","readOnly":true},"latest_version":{"type":"integer","description":"The latest version number of this category","format":"int32","readOnly":true},"enable_rtl":{"type":"boolean","description":"Indicates if Right to Left alignment is enabled for the category language"},"hidden":{"type":"boolean","description":"Indicates if the category is visible on the site"},"status":{"enum":["draft","published"],"type":"string","allOf":[{"$ref":"#/components/schemas/ArticleStatusCustomer"}],"description":"The status of the category: 0 - Draft, 3 - Published","x-enumNames":["Draft","Published"],"x-enum-varnames":["Draft","Published"],"x-ms-enum":{"name":"ArticleStatusCustomer","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.","nullable":true},"order":{"type":"integer","description":"The position inside the parent category","format":"int32"},"created_by":{"type":"string","description":"The ID of the user that created the category","nullable":true},"authors":{"type":"array","items":{"$ref":"#/components/schemas/UserProfileCustomer"},"description":"The list of authors that contributed to this category","nullable":true},"created_at":{"type":"string","description":"The date the category was created","format":"date-time","readOnly":true},"modified_at":{"type":"string","description":"The date the category was last modified","format":"date-time","readOnly":true},"slug":{"type":"string","description":"The slug of the category","nullable":true,"readOnly":true},"is_fall_back_content":{"type":"boolean","description":"Indicates whether the category content is a fallback of the default language content or not"}},"additionalProperties":false},"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}},"UserProfileCustomer":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the team account.","nullable":true,"readOnly":true},"first_name":{"type":"string","description":"First name.","nullable":true},"last_name":{"type":"string","description":"Last name.","nullable":true},"email_id":{"type":"string","description":"Email address.","nullable":true},"profile_logo_url":{"type":"string","description":"URL of the user's profile picture (with SAS token appended for private/mixed projects).","nullable":true},"user_role":{"enum":["administrator","editor","draftWriter","reader","owner"],"type":"string","allOf":[{"$ref":"#/components/schemas/UserAccess"}],"description":"The user's V1 role. See Document360.Core.Enums.UserAccess for the available values.","x-enumNames":["Administrator","Editor","DraftWriter","Reader","Owner"],"x-enum-varnames":["Administrator","Editor","DraftWriter","Reader","Owner"],"x-ms-enum":{"name":"UserAccess","modelAsString":true}},"last_login_at":{"type":"string","description":"Timestamp of the most recent successful sign-in. `null` if the user has never signed in.","format":"date-time","nullable":true,"readOnly":true},"unique_user_name":{"type":"string","description":"The unique display name (handle) for the user.","nullable":true},"sso_user_type":{"enum":["normalUser","ssoUser","ssoUserInvited"],"type":"string","allOf":[{"$ref":"#/components/schemas/SSOUserTypes"}],"description":"For SSO users, indicates the SSO provisioning state (e.g. invited, active).","x-enumNames":["NormalUser","SSOUser","SSOUserInvited"],"x-enum-varnames":["NormalUser","SSOUser","SSOUserInvited"],"x-ms-enum":{"name":"SSOUserTypes","modelAsString":true}},"is_sso_user":{"type":"boolean","description":"`True` when the user was provisioned via SSO."},"is_active":{"type":"boolean","description":"`True` when the user is active (not deactivated or pending invitation)."}},"additionalProperties":false,"description":"V1 team account profile — identity, contact details, role, login state, and SSO flags. Returned by `GET /v1/teams` and `GET /v1/teams/{userId}`."},"UserAccess":{"enum":["administrator","editor","draftWriter","reader","owner"],"type":"string","description":"Predefined access role for a project user. Used in the V1 Customer API to assign or filter users by role. Newer integrations should prefer the role IDs exposed by `GET /v2/teams/roles`.","x-enumNames":["Administrator","Editor","DraftWriter","Reader","Owner"],"x-enum-varnames":["Administrator","Editor","DraftWriter","Reader","Owner"],"x-ms-enum":{"name":"UserAccess","modelAsString":true}},"SSOUserTypes":{"enum":["normalUser","ssoUser","ssoUserInvited"],"type":"string","description":"SSO user type 0 - Normal user, 1 - SSO user, 2 - Invited SSO user","x-enumNames":["NormalUser","SSOUser","SSOUserInvited"],"x-enum-varnames":["NormalUser","SSOUser","SSOUserInvited"],"x-ms-enum":{"name":"SSOUserTypes","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"}}}}