> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudhumans.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a category > Create a category in the portal. Its `id` is what goes into `category_id` when [creating an article](/api-reference/cloudchat/endpoints/create-an-article), and its locale is what decides that article's language and translation target. The locale has to be one of the portal's `allowed_locales` — [list portals](/api-reference/cloudchat/endpoints/list-portals) shows the current list and [updating the portal](/api-reference/cloudchat/endpoints/update-a-portal) is how you add one. Requires being an administrator of the account or a member of the portal. export const CloudChatYourValues = () => { const STORAGE_KEY = "cloudchat-api-selected-account"; const CREDENTIALS_HREF = "/api-reference/cloudchat/credentials"; const [saved, setSaved] = useState(null); const [ready, setReady] = useState(false); useEffect(() => { let value = null; try { const raw = window.localStorage.getItem(STORAGE_KEY); if (raw) { const parsed = JSON.parse(raw); if (parsed && parsed.instance && parsed.account) { value = { instance: String(parsed.instance), account: String(parsed.account), name: typeof parsed.name === "string" && parsed.name ? parsed.name : null }; } } } catch (error) { value = null; } setSaved(value); setReady(true); }, []); const shell = "not-prose rounded-xl border border-gray-200 dark:border-white/10 bg-gray-50 dark:bg-white/5 px-4 py-3 mb-6"; if (!ready || !saved) { return

Every request below needs your cloudchat-instance header and your account id.{" "} Paste your token {" "} and they will show up here, ready to copy.

; } return
cloudchat-instance {saved.instance}
accountId {saved.account}
{saved.name && {saved.name}} Change
; }; ## OpenAPI ````yaml api-reference/specs/cloudchat/v1.json POST /v1/accounts/{accountId}/portals/{portalSlug}/categories openapi: 3.0.1 info: title: Cloud Chat API version: v1 description: >- The curated public surface of Cloud Chat. Every call needs two things: the Bearer token from `POST /auth/v1/signin`, and the `cloudchat-instance` header that says which Cloud Chat instance your company lives on. If you don't know your instance value, the [Find your credentials](/api-reference/cloudchat/credentials) page reads it out of your own token in the browser. servers: - url: https://api.cloudhumans.com/cloudchat description: Production security: - bearerAuth: [] tags: - name: Canned Responses description: >- Canned responses — the shortcuts agents expand while replying. Each one belongs to a single account and is identified by its short code. - name: Conversations description: >- Read-only access to the conversations of an account. What you can see follows the same rule as the dashboard: an administrator token sees every inbox, an agent token only the inboxes it is a member of. - name: Help Center description: >- Portals, categories and articles of the help center — the public FAQ your customers read. - name: Uploads description: Store the images help center articles embed. - name: Labels description: >- Read-only access to the labels an account has defined. A label is a tag conversations and contacts carry; this endpoint only lists the label definitions themselves. - name: Inboxes description: >- Read-only access to the inboxes a token can see — every inbox of the account for an administrator, only its memberships for an agent. Never includes the channel's credentials. - name: Agents description: >- Read-only access to the human and AI agents of an account. A hidden admin (the platform's own support user) never appears, on the list or by id. - name: Teams description: >- Teams group agents for assignment. Listing and reading are open to any member; creating and updating a team, and managing its membership, require an administrator token. A system-managed team (provisioned by the platform) can be read like any other but never updated. - name: Macros description: >- Macros bundle a sequence of actions an agent runs against a conversation from the dashboard. This surface lets you list, read and write macro definitions — running one is not part of the v1 contract. A macro is either `global` (visible to the whole account) or `personal` (visible only to its author); an agent token can only create personal macros. - name: Automation Rules description: >- Read-only access to the account's automation rules — administrator only. An agent token gets a 403 on every operation in this group. - name: Availability Reasons description: >- The reasons an agent can go `busy` for, configured per account. Listing is open to any member; creating, updating and deleting require an administrator token. Deleting is a soft delete — the reason disappears from listings but agents' past availability history keeps referencing it. paths: /v1/accounts/{accountId}/portals/{portalSlug}/categories: post: tags: - Help Center summary: Create a category description: >- Create a category in the portal. Its `id` is what goes into `category_id` when [creating an article](/api-reference/cloudchat/endpoints/create-an-article), and its locale is what decides that article's language and translation target. The locale has to be one of the portal's `allowed_locales` — [list portals](/api-reference/cloudchat/endpoints/list-portals) shows the current list and [updating the portal](/api-reference/cloudchat/endpoints/update-a-portal) is how you add one. Requires being an administrator of the account or a member of the portal. operationId: createHelpCenterCategory parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/CloudChatInstance' - $ref: '#/components/parameters/PortalSlug' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CategoryCreateRequest' example: category: name: Primeiros passos description: Comece por aqui. locale: pt_BR responses: '201': description: The category as stored. content: application/json: schema: $ref: '#/components/schemas/Category' example: id: 31 slug: primeiros-passos name: Primeiros passos description: Comece por aqui. locale: pt_BR position: null parent_category_id: null associated_category_id: null created_at: '2026-08-19T18:10:52.318Z' updated_at: '2026-08-19T18:10:52.318Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Two situations answer with this code: the account is suspended, or your user is neither an administrator of the account nor a member of this portal. Ask an administrator to add you to the portal's members. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: forbidden message: You are not allowed to perform this action. '404': $ref: '#/components/responses/NotFound' '422': description: >- A refused value, with `error.details` naming the field: a missing `name`, a `locale` outside the portal's `allowed_locales`, a `slug` you chose that another category of this portal already uses in that locale (`code: "taken"`), or an `associated_category_id` that is not a category of this portal. content: application/json: schema: $ref: '#/components/schemas/ValidationError' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' components: parameters: AccountId: name: accountId in: path required: true description: >- Your Cloud Chat account. It has to be an account your token grants membership on, and it has to live on the instance in the `cloudchat-instance` header — the two travel together. Account numbers are only unique **within** an instance, so the same number is a different company on another instance. Usually a mismatched pair fails closed with a 401, because your user does not exist on the other instance — but if your identity happens to exist on both, the call succeeds against the other company's data, silently. Read it and you are looking at the wrong help center; write it and you have stored into the wrong account. Send the two values that were given to you together, and never try a number to see what answers. schema: type: integer example: 1 CloudChatInstance: name: cloudchat-instance in: header required: true description: >- Your Cloud Chat instance ID — an integer, fixed for your company, told at onboarding. [The API overview](/api-reference/cloudchat/overview#two-headers-every-call) explains how instances work, how to find yours, and the errors a wrong or missing value produces. schema: type: integer example: 1 PortalSlug: name: portalSlug in: path required: true description: >- The portal's slug — the URL-safe handle you see in its public address (`/hc//...`), not a numeric id. [List portals](/api-reference/cloudchat/endpoints/list-portals) returns every slug on the account. Note the asymmetry: portals are addressed by slug, articles by numeric id. schema: type: string example: acme-help schemas: CategoryCreateRequest: type: object description: The category goes under a `category` wrapper. Only `name` is required. required: - category properties: category: type: object required: - name properties: name: type: string example: Primeiros passos description: Display name shown on the help center. description: type: string example: Comece por aqui. description: Short text shown under the name. locale: type: string example: pt_BR description: >- Defaults to the portal's `default_locale`. It has to be one of the portal's `allowed_locales`, otherwise the call is refused as `validation_failed` naming `locale` and listing the locales that would work — [update the portal](/api-reference/cloudchat/endpoints/update-a-portal) to allow one more first. Articles created in this category inherit this locale. slug: type: string example: primeiros-passos description: >- URL-safe handle. Omit it and one is derived from the name, with a counter appended if that handle is already used — a derived slug never fails and never quietly reuses an existing category. Send one explicitly and the collision is yours: a slug already used **in that locale** is refused with `code: "taken"`. The same slug in a different locale is allowed, which is the normal shape of a bilingual help center. associated_category_id: type: integer example: 31 description: >- Links this category to the same category in another locale, so the help center can offer the translation. Pass the `id` of any category of the family — the server normalizes it to the family root. Must belong to this portal. Category: type: object description: A category of one help center portal. required: - id - slug - name - locale - position - created_at - updated_at properties: id: type: integer example: 12 description: What goes in `category_id` when creating or updating an article. slug: type: string example: getting-started name: type: string example: Getting Started description: type: string nullable: true example: First steps with the product. locale: type: string example: en description: >- An article created in this category inherits this locale, and [translate](/api-reference/cloudchat/endpoints/translate-an-article) translates into it. Older categories can carry a locale that is no longer among the portal's `allowed_locales`: they are still listed and still render, but any write to them is refused until that locale is allowed again through [updating the portal](/api-reference/cloudchat/endpoints/update-a-portal). position: type: integer nullable: true example: 10 description: >- The order the help center renders, ascending. Null on a category that never got one — which is most of them, because nothing assigns a position automatically. The listing puts those last. parent_category_id: type: integer nullable: true example: null description: Set when the category is nested under another. associated_category_id: type: integer nullable: true example: null description: >- Root category linking the translations of the same category across locales. created_at: type: string format: date-time example: '2026-05-02T11:04:17.000Z' updated_at: type: string format: date-time example: '2026-08-10T14:32:05.123Z' Error: type: object description: The error envelope every Cloud Chat API response uses. required: - error properties: error: type: object required: - code - message properties: code: type: string description: >- The stable, machine-readable reason. Branch on this, never on `message`. enum: - unauthorized - forbidden - not_found - validation_failed - bad_request - internal_error example: not_found message: type: string description: >- The reason in words, localized to your account's language (English, Spanish or Brazilian Portuguese; English when the account is set to anything else). Wording changes with the account and between releases, so never match on it. Two cases stay in English whatever the account is set to: `unauthorized`, decided before any account is known, and the account-level `not_found`, which must not reveal the account's language. example: Resource could not be found. details: type: array description: >- Present on some rejections — a 400 for a refused query parameter or upload mode, for example. One entry per offending field, localized to the account's language like `message` — match on `code` and `field`, never on the text. items: type: object required: - field - code - message properties: field: type: string description: Which request field the rule was about. code: type: string description: Stable, machine-readable reason. message: type: string description: The rule in words. ValidationError: type: object description: A `validation_failed` error, which carries `details`. required: - error properties: error: type: object required: - code - message - details properties: code: type: string enum: - validation_failed example: validation_failed message: type: string description: >- Localized to the account's language, like every other envelope message. example: The request payload is invalid. details: type: array description: >- One entry per rejected field. Unlike the envelope message above, the texts come from the model layer and are in English in practice (the model layer ships no translations) — match on code and field, never on the text. items: type: object required: - field - code - message properties: field: type: string description: >- Which request field the rule was about — `short_code` or `content`. A rule that is not tied to either is reported as `base`, so treat `base` as "the payload as a whole" rather than a field you can highlight. enum: - short_code - content - base example: short_code code: type: string description: >- Which rule it broke — `blank` for a missing or empty value, `taken` for a `short_code` already used on the account. example: taken message: type: string example: has already been taken GatewayError: type: object description: >- Rejected by the gateway before Cloud Chat saw it, so it does not use the `error` envelope. required: - message properties: message: type: string example: API rate limit exceeded request_id: type: string description: Gateway request id. Quote it when reporting a problem. example: f3f7567638d4b65a8003057d0c77d275 responses: BadRequest: description: >- The request itself is malformed, before any value is validated: - a body that isn't valid JSON, or one with no `canned_response` wrapper, - a `canned_response` that isn't an object (`{"canned_response": "text"}`), - `page`, `per_page`, `search` or `sort` sent as an array or a nested object (`?page[]=1`, `?sort[x]=y`) instead of a plain value, - **the `cloudchat-instance` header missing or holding a value we don't route,** - an `accountId` that is not a number — including the literal `{accountId}` that some API clients send when the argument is left unset. This one answers with the normal envelope and `error.details` naming `accountId`, and it is deliberately **not** a 404: a 404 would mean the account cannot be reached, while this means the value was never an account id at all, so re-read the argument instead of trying other numbers. **Two different shapes answer with 400, and the difference will bite you on day one.** That last case is rejected before the request reaches the API, so `error` is a plain **string** instead of the usual object: ```json { "error": "" } ``` Every other 400 uses the normal envelope, where `error` is an object with `code` and `message`. Reading `error.code` without checking the type first throws on the missing-header case — which is the most likely 400 of your first integration. Check `typeof error === "string"` first, or read `error?.code` defensively. A 400 always means fix the request shape; it never means a value was rejected. Rejected values are 422. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: bad_request message: The request is malformed. Unauthorized: description: >- No Bearer token, or one that is expired, malformed, or not a Cognito token. Sign in again for a fresh `id_token`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: >- Authentication is required. Send a valid Bearer token in the Authorization header. NotFound: description: >- The resource is not there for you. Three situations answer with this code, and the first two apply to **every** endpoint — the account is resolved before anything else runs, so a list or a create fails this way too: - the account does not exist on this instance, - the account exists but your token has no membership on it, - on an endpoint that names one, the resource it names (a canned response, a portal, an article) does not exist where the path says it does. The first two are deliberately indistinguishable — same status, same body, and the message stays in English in both, since translating it would reveal the account's configured language. So you cannot use this endpoint to find out which account ids exist. The third case is localized like every other error, which is safe because you only reach it once membership is established. Either way a 404 is not worth retrying. Check the `accountId`, the `cloudchat-instance` value, and that your user is a member of the account. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_found message: Resource could not be found. TooManyRequests: description: >- Rate limited per source IP. Note the envelope: this one is `{ "message": ... }`, because the request never reached the API. Don't hardcode the limit — read it from the response. `Retry-After` says how many seconds to wait, and every response (not just this one) carries `ratelimit-limit`, `ratelimit-remaining` and `ratelimit-reset`, the last in seconds. content: application/json: schema: $ref: '#/components/schemas/GatewayError' example: message: API rate limit exceeded InternalError: description: >- Something failed on our side. The response never carries the underlying error, but it is reported to our monitoring automatically — no need to file anything for a one-off. Retrying is reasonable, with one caveat on `POST`: a 500 does not prove the write did not happen, so a retry can come back `422` with `short_code` already taken. That 422 means the first attempt succeeded — list the account and confirm before treating it as a failure. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: internal_error message: An unexpected error occurred. Please try again later. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- The `id_token` from `POST /auth/v1/signin`, sent as `Authorization: Bearer `. Not the `access_token` — that one does not carry the identity Cloud Chat authorizes on. ````