{ "openapi": "3.1.0", "x-tagGroups": [ { "name": "Content", "tags": [ "Articles", "Article drafts", "Article revisions", "Article translations", "Collections", "Sections" ] }, { "name": "Insights", "tags": [ "Analytics", "Feedback", "Assistant conversations" ] }, { "name": "Platform", "tags": [ "Users", "Tasks", "Webhooks" ] } ], "info": { "title": "Ferndesk Public API", "description": "Programmatic access to manage your Ferndesk help center — articles (drafts, revisions, translations), collections, sections, users, AI tasks, assistant conversations, feedback, and analytics.\n\n## Authentication & scopes\n\nEvery request must send your API key as a bearer token:\n\n```\nAuthorization: Bearer fdsk_xxx\n```\n\nAPI keys can be restricted to **scopes**. Every operation declares the scope it needs in the machine-readable `x-required-scopes` extension, shown alongside its authentication requirement. A request whose key lacks that scope returns **403** with `{ error, code: \"missing_scope\", scope }`.\n\n| Scope | Grants |\n| --- | --- |\n| `content:read` | Read and search help center articles, collections, sections, and translations |\n| `content:write` | Create and edit article drafts, users, tasks; move articles and collections |\n| `content:publish` | Publish, unpublish, restore, and trash content (make changes live) |\n| `analytics:read` | Read help center reporting, analytics, and article feedback |\n| `conversations:read` | Read AI assistant conversations and transcripts |\n| `webhooks:manage` | Create and manage outbound webhook subscriptions |\n\n**Scope implication:** granting `content:write` or `content:publish` implicitly grants `content:read` — a key that can change content can always read it.\n\n**Legacy keys:** API keys minted before scoping shipped have null scopes, which grants **full access** and puts the request in [legacy compatibility mode](#legacy-compatibility-mode). Newly issued keys always carry explicit scopes.\n\n## Pagination\n\nList endpoints use cursor pagination: pass `page_size` (1-100, default 20) and the `next_cursor` from the previous response as `start_cursor`. Responses have the shape `{ results, has_more, next_cursor }`. Article search is relevance-ranked and returns up to 100 results without a cursor.\n\n## Rate limits\n\nA **global** limit of **1,000 requests per minute per API key** applies to every endpoint. Some write endpoints carry an additional, stricter per-operation cap:\n\n| Operation | Limit |\n| --- | --- |\n| `POST /articles` (create article) | 60 / hour |\n| `POST /tasks` (create task) | 10 / hour |\n| `POST /feedback` (create feedback) | 300 / hour |\n| `POST /webhooks/{id}/test` (test delivery) | 5 / minute |\n\nExceeding any limit returns **429** with body `{ \"error\": \"Rate limit exceeded\", \"code\": \"rate_limited\" }` and a `Retry-After` header (seconds until you may retry).\n\n## Legacy compatibility mode\n\nConsumers built against the pre-2026-07 API keep working unchanged via a legacy compatibility mode. A request runs in legacy mode when it sends the old `limit`/`offset` pagination params, or when it authenticates with an API key minted before scopes existed (its `scopes` are null) and sends no pagination params. In legacy mode, list endpoints (`/articles`, `/articles/search`, `/collections`, `/sections`, `/users`, `/tasks`) return the old `{ items, limit, offset, total }` envelope; ranked article search uses a stable bounded universe of up to 1,000 matches so offsets and totals remain consistent. `GET`/`POST`/`PATCH /articles` restore the old default status visibility (drafts included, trashed never), force-publish on create, and immediate-publish on content patches. Every legacy-mode response carries `Deprecation: true` and `X-Ferndesk-Api-Mode: legacy`. To use the current contract, send `page_size`/`start_cursor` (lists) or an explicit `publish` field (create). The shim is self-sunsetting — every newly issued key carries scopes and defaults to the current contract — and will be removed once pre-scope keys age out.\n\n## Webhook deliveries\n\nRegister an HTTPS endpoint, subscribe it to event types (or `*` for all), and Ferndesk POSTs a signed JSON envelope to it whenever a matching event occurs. Every delivery body is the envelope `{ id, type, created_at, data }`, where `id` is a unique `whevt_` event id.\n\n### Signature verification\n\nEach request carries three headers:\n\n- `webhook-id`: the envelope `id` (`whevt_...`)\n- `webhook-timestamp`: unix seconds when the request was signed\n- `webhook-signature`: a space-separated list of `v1,` tokens (a list so secret rotation can send multiple)\n\nThe signature is an HMAC-SHA256 over the exact string `` `${webhook-id}.${webhook-timestamp}.${raw-request-body}` ``, then base64-encoded. The HMAC key is your endpoint secret with the `whsec_` prefix stripped **and the remainder base64-decoded** — the raw decoded bytes are the key, not the ASCII text of the secret (this matches the Standard Webhooks / Svix scheme). Verify like so (pseudo-code):\n\n```\nsigned = webhook_id + \".\" + webhook_timestamp + \".\" + raw_body\nkey = base64_decode(secret.removeprefix(\"whsec_\"))\nexpected = base64(hmac_sha256(key, signed))\n// constant-time compare `expected` against each `v1,` token in the\n// webhook-signature header; reject if none match, and reject stale timestamps.\n```\n\nThe signing `secret` (`whsec_...`) is returned once when you create an endpoint. Endpoint reads intentionally omit it, so store the creation response securely. Use POST /webhooks/{id}/test to send a signed `webhook.test` delivery end-to-end.\n\n## Errors\n\nErrors return `{ error: string, code: string }`. Conflict responses (409) carry additional context, e.g. stale publishes return `code: draft_outdated` with `currentVersion` and `draftBaseVersion`.", "version": "1.0.0" }, "servers": [ { "url": "https://api.ferndesk.com/v1", "description": "Production" }, { "url": "http://localhost:8500/public-api/v1", "description": "Local development" } ], "tags": [ { "name": "Articles", "description": "The help center articles themselves, from creation through publishing, trashing, and restoring." }, { "name": "Article drafts", "description": "Open drafts, where article edits are staged before they go live." }, { "name": "Article revisions", "description": "The version history captured on every publish, with diffs and restores." }, { "name": "Article translations", "description": "Per-locale versions of your articles, and the gaps between them." }, { "name": "Collections", "description": "Collections, the groups of related articles inside a section." }, { "name": "Sections", "description": "Sections, the top level of your help center navigation." }, { "name": "Analytics", "description": "Reporting on how readers find and use your help center." }, { "name": "Feedback", "description": "The helpful-or-not verdicts readers leave on articles, and their triage state." }, { "name": "Assistant conversations", "description": "Conversations readers had with the AI assistant, and their sanitized transcripts." }, { "name": "Users", "description": "Help center end users and the attributes audience rules match on." }, { "name": "Tasks", "description": "AI tasks that write and update help center content on your behalf." }, { "name": "Webhooks", "description": "Endpoints that receive signed event deliveries, and the events Ferndesk sends them." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "All requests require a Bearer token in the `Authorization` header. API keys are prefixed with `fdsk_` and should be kept secret. You can generate and manage keys from the [Developer settings](https://ferndesk.com/app/settings/developers) page.\n\nKeys can be restricted to any subset of these scopes (each endpoint lists the scope it requires via `x-required-scopes`):\n\n- `content:read`: Read and search help center articles, collections, sections, and translations\n- `content:write`: Create and edit article drafts, users, tasks; move articles and collections\n- `content:publish`: Publish, unpublish, restore, and trash content (make changes live)\n- `analytics:read`: Read help center reporting, analytics, and article feedback\n- `conversations:read`: Read AI assistant conversations and transcripts\n- `webhooks:manage`: Create and manage outbound webhook subscriptions\n\nGranting `content:write` or `content:publish` implies `content:read`. Keys minted before scoping have null scopes = full access (legacy mode)." } } }, "security": [ { "bearerAuth": [] } ], "webhooks": { "article.published": { "post": { "summary": "Article published", "description": "Fires when an article’s live content changes, including its first publish.", "operationId": "webhookArticlePublished", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "Envelope `id`, unique per event.", "schema": { "type": "string", "examples": [ "whevt_01JXYC5R2K9M" ] } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when the request was signed; reject stale values.", "schema": { "type": "string", "examples": [ "1752096000" ] } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated `v1,` tokens — several during secret rotation — computed as described under Signature verification.", "schema": { "type": "string", "examples": [ "v1,K5oT8v...base64..." ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Delivery envelope; `data` varies by event type.", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "Event identifier, repeated in the `webhook-id` header.", "examples": [ "whevt_01JXYC5R2K9M" ] }, "type": { "type": "string", "description": "Event type carried by this delivery.", "enum": [ "article.published" ], "examples": [ "article.published" ] }, "created_at": { "type": "string", "description": "When the event was created.", "examples": [ "2026-07-09T18:25:43.511Z" ] }, "data": { "type": "object", "description": "Article snapshot at the moment the event fired.", "required": [ "id", "title", "slug", "status", "version", "url", "collection_id", "published_by_member_id", "source" ], "properties": { "id": { "type": "string", "description": "Article identifier.", "examples": [ "art_01JXY9AZK4KV" ] }, "title": { "type": "string", "description": "Article title.", "examples": [ "Getting started with API keys" ] }, "slug": { "type": "string", "description": "URL slug.", "examples": [ "getting-started-api-keys" ] }, "status": { "type": [ "string", "null" ], "description": "Publish status.", "examples": [ "published" ] }, "version": { "type": "integer", "description": "Live version number.", "examples": [ 3 ] }, "url": { "type": [ "string", "null" ], "description": "Public URL, or null when it cannot be resolved.", "examples": [ "https://docs.example.com/getting-started-api-keys-A1B2C3" ] }, "collection_id": { "type": [ "string", "null" ], "description": "Collection grouping the article.", "examples": [ "col_01JXYA6ABN52" ] }, "published_by_member_id": { "type": [ "string", "null" ], "description": "Member who triggered the change.", "examples": [ "mem_01JXYB8W4Q2H" ] }, "source": { "type": [ "string", "null" ], "description": "Write channel that produced the change.", "examples": [ "api" ] } } } } } } } }, "responses": { "2xx": { "description": "Delivery acknowledged; anything else is retried with backoff." } } } }, "article.updated": { "post": { "summary": "Article updated", "description": "Fires when the public representation of a published article changes, such as its metadata.", "operationId": "webhookArticleUpdated", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "Envelope `id`, unique per event.", "schema": { "type": "string", "examples": [ "whevt_01JXYC5R2K9M" ] } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when the request was signed; reject stale values.", "schema": { "type": "string", "examples": [ "1752096000" ] } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated `v1,` tokens — several during secret rotation — computed as described under Signature verification.", "schema": { "type": "string", "examples": [ "v1,K5oT8v...base64..." ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Delivery envelope; `data` varies by event type.", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "Event identifier, repeated in the `webhook-id` header.", "examples": [ "whevt_01JXYC5R2K9M" ] }, "type": { "type": "string", "description": "Event type carried by this delivery.", "enum": [ "article.updated" ], "examples": [ "article.updated" ] }, "created_at": { "type": "string", "description": "When the event was created.", "examples": [ "2026-07-09T18:25:43.511Z" ] }, "data": { "type": "object", "description": "Article snapshot at the moment the event fired.", "required": [ "id", "title", "slug", "status", "version", "url", "collection_id", "published_by_member_id", "source" ], "properties": { "id": { "type": "string", "description": "Article identifier.", "examples": [ "art_01JXY9AZK4KV" ] }, "title": { "type": "string", "description": "Article title.", "examples": [ "Getting started with API keys" ] }, "slug": { "type": "string", "description": "URL slug.", "examples": [ "getting-started-api-keys" ] }, "status": { "type": [ "string", "null" ], "description": "Publish status.", "examples": [ "published" ] }, "version": { "type": "integer", "description": "Live version number.", "examples": [ 3 ] }, "url": { "type": [ "string", "null" ], "description": "Public URL, or null when it cannot be resolved.", "examples": [ "https://docs.example.com/getting-started-api-keys-A1B2C3" ] }, "collection_id": { "type": [ "string", "null" ], "description": "Collection grouping the article.", "examples": [ "col_01JXYA6ABN52" ] }, "published_by_member_id": { "type": [ "string", "null" ], "description": "Member who triggered the change.", "examples": [ "mem_01JXYB8W4Q2H" ] }, "source": { "type": [ "string", "null" ], "description": "Write channel that produced the change.", "examples": [ "api" ] } } } } } } } }, "responses": { "2xx": { "description": "Delivery acknowledged; anything else is retried with backoff." } } } }, "article.unpublished": { "post": { "summary": "Article unpublished", "description": "Fires when a published article is taken offline.", "operationId": "webhookArticleUnpublished", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "Envelope `id`, unique per event.", "schema": { "type": "string", "examples": [ "whevt_01JXYC5R2K9M" ] } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when the request was signed; reject stale values.", "schema": { "type": "string", "examples": [ "1752096000" ] } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated `v1,` tokens — several during secret rotation — computed as described under Signature verification.", "schema": { "type": "string", "examples": [ "v1,K5oT8v...base64..." ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Delivery envelope; `data` varies by event type.", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "Event identifier, repeated in the `webhook-id` header.", "examples": [ "whevt_01JXYC5R2K9M" ] }, "type": { "type": "string", "description": "Event type carried by this delivery.", "enum": [ "article.unpublished" ], "examples": [ "article.unpublished" ] }, "created_at": { "type": "string", "description": "When the event was created.", "examples": [ "2026-07-09T18:25:43.511Z" ] }, "data": { "type": "object", "description": "Article snapshot at the moment the event fired.", "required": [ "id", "title", "slug", "status", "version", "url", "collection_id", "published_by_member_id", "source" ], "properties": { "id": { "type": "string", "description": "Article identifier.", "examples": [ "art_01JXY9AZK4KV" ] }, "title": { "type": "string", "description": "Article title.", "examples": [ "Getting started with API keys" ] }, "slug": { "type": "string", "description": "URL slug.", "examples": [ "getting-started-api-keys" ] }, "status": { "type": [ "string", "null" ], "description": "Publish status.", "examples": [ "published" ] }, "version": { "type": "integer", "description": "Live version number.", "examples": [ 3 ] }, "url": { "type": [ "string", "null" ], "description": "Public URL, or null when it cannot be resolved.", "examples": [ "https://docs.example.com/getting-started-api-keys-A1B2C3" ] }, "collection_id": { "type": [ "string", "null" ], "description": "Collection grouping the article.", "examples": [ "col_01JXYA6ABN52" ] }, "published_by_member_id": { "type": [ "string", "null" ], "description": "Member who triggered the change.", "examples": [ "mem_01JXYB8W4Q2H" ] }, "source": { "type": [ "string", "null" ], "description": "Write channel that produced the change.", "examples": [ "api" ] } } } } } } } }, "responses": { "2xx": { "description": "Delivery acknowledged; anything else is retried with backoff." } } } }, "article.deleted": { "post": { "summary": "Article trashed", "description": "Fires when an article is moved to the trash, from which it can still be restored.", "operationId": "webhookArticleDeleted", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "Envelope `id`, unique per event.", "schema": { "type": "string", "examples": [ "whevt_01JXYC5R2K9M" ] } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when the request was signed; reject stale values.", "schema": { "type": "string", "examples": [ "1752096000" ] } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated `v1,` tokens — several during secret rotation — computed as described under Signature verification.", "schema": { "type": "string", "examples": [ "v1,K5oT8v...base64..." ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Delivery envelope; `data` varies by event type.", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "Event identifier, repeated in the `webhook-id` header.", "examples": [ "whevt_01JXYC5R2K9M" ] }, "type": { "type": "string", "description": "Event type carried by this delivery.", "enum": [ "article.deleted" ], "examples": [ "article.deleted" ] }, "created_at": { "type": "string", "description": "When the event was created.", "examples": [ "2026-07-09T18:25:43.511Z" ] }, "data": { "type": "object", "description": "Article snapshot at the moment the event fired.", "required": [ "id", "title", "slug", "status", "version", "url", "collection_id", "published_by_member_id", "source" ], "properties": { "id": { "type": "string", "description": "Article identifier.", "examples": [ "art_01JXY9AZK4KV" ] }, "title": { "type": "string", "description": "Article title.", "examples": [ "Getting started with API keys" ] }, "slug": { "type": "string", "description": "URL slug.", "examples": [ "getting-started-api-keys" ] }, "status": { "type": [ "string", "null" ], "description": "Publish status.", "examples": [ "published" ] }, "version": { "type": "integer", "description": "Live version number.", "examples": [ 3 ] }, "url": { "type": [ "string", "null" ], "description": "Public URL, or null when it cannot be resolved.", "examples": [ "https://docs.example.com/getting-started-api-keys-A1B2C3" ] }, "collection_id": { "type": [ "string", "null" ], "description": "Collection grouping the article.", "examples": [ "col_01JXYA6ABN52" ] }, "published_by_member_id": { "type": [ "string", "null" ], "description": "Member who triggered the change.", "examples": [ "mem_01JXYB8W4Q2H" ] }, "source": { "type": [ "string", "null" ], "description": "Write channel that produced the change.", "examples": [ "api" ] } } } } } } } }, "responses": { "2xx": { "description": "Delivery acknowledged; anything else is retried with backoff." } } } }, "article.restored": { "post": { "summary": "Article restored", "description": "Fires when a trashed article is restored.", "operationId": "webhookArticleRestored", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "Envelope `id`, unique per event.", "schema": { "type": "string", "examples": [ "whevt_01JXYC5R2K9M" ] } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when the request was signed; reject stale values.", "schema": { "type": "string", "examples": [ "1752096000" ] } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated `v1,` tokens — several during secret rotation — computed as described under Signature verification.", "schema": { "type": "string", "examples": [ "v1,K5oT8v...base64..." ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Delivery envelope; `data` varies by event type.", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "Event identifier, repeated in the `webhook-id` header.", "examples": [ "whevt_01JXYC5R2K9M" ] }, "type": { "type": "string", "description": "Event type carried by this delivery.", "enum": [ "article.restored" ], "examples": [ "article.restored" ] }, "created_at": { "type": "string", "description": "When the event was created.", "examples": [ "2026-07-09T18:25:43.511Z" ] }, "data": { "type": "object", "description": "Article snapshot at the moment the event fired.", "required": [ "id", "title", "slug", "status", "version", "url", "collection_id", "published_by_member_id", "source" ], "properties": { "id": { "type": "string", "description": "Article identifier.", "examples": [ "art_01JXY9AZK4KV" ] }, "title": { "type": "string", "description": "Article title.", "examples": [ "Getting started with API keys" ] }, "slug": { "type": "string", "description": "URL slug.", "examples": [ "getting-started-api-keys" ] }, "status": { "type": [ "string", "null" ], "description": "Publish status.", "examples": [ "published" ] }, "version": { "type": "integer", "description": "Live version number.", "examples": [ 3 ] }, "url": { "type": [ "string", "null" ], "description": "Public URL, or null when it cannot be resolved.", "examples": [ "https://docs.example.com/getting-started-api-keys-A1B2C3" ] }, "collection_id": { "type": [ "string", "null" ], "description": "Collection grouping the article.", "examples": [ "col_01JXYA6ABN52" ] }, "published_by_member_id": { "type": [ "string", "null" ], "description": "Member who triggered the change.", "examples": [ "mem_01JXYB8W4Q2H" ] }, "source": { "type": [ "string", "null" ], "description": "Write channel that produced the change.", "examples": [ "api" ] } } } } } } } }, "responses": { "2xx": { "description": "Delivery acknowledged; anything else is retried with backoff." } } } }, "translation.published": { "post": { "summary": "Translation published", "description": "Fires when a translation of an article goes live in one locale.", "operationId": "webhookTranslationPublished", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "Envelope `id`, unique per event.", "schema": { "type": "string", "examples": [ "whevt_01JXYC5R2K9M" ] } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when the request was signed; reject stale values.", "schema": { "type": "string", "examples": [ "1752096000" ] } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated `v1,` tokens — several during secret rotation — computed as described under Signature verification.", "schema": { "type": "string", "examples": [ "v1,K5oT8v...base64..." ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Delivery envelope; `data` varies by event type.", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "Event identifier, repeated in the `webhook-id` header.", "examples": [ "whevt_01JXYC5R2K9M" ] }, "type": { "type": "string", "description": "Event type carried by this delivery.", "enum": [ "translation.published" ], "examples": [ "translation.published" ] }, "created_at": { "type": "string", "description": "When the event was created.", "examples": [ "2026-07-09T18:25:43.511Z" ] }, "data": { "type": "object", "required": [ "article_id", "language", "title" ], "properties": { "article_id": { "type": "string", "description": "Article that was translated.", "examples": [ "art_01JXY9AZK4KV" ] }, "language": { "type": "string", "description": "Locale.", "examples": [ "fr" ] }, "title": { "type": [ "string", "null" ], "description": "Localized title.", "examples": [ "Débuter avec les clés API" ] } } } } } } } }, "responses": { "2xx": { "description": "Delivery acknowledged; anything else is retried with backoff." } } } }, "feedback.received": { "post": { "summary": "Feedback received", "description": "Fires when a reader rates an article in the help center or widget.", "operationId": "webhookFeedbackReceived", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "Envelope `id`, unique per event.", "schema": { "type": "string", "examples": [ "whevt_01JXYC5R2K9M" ] } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when the request was signed; reject stale values.", "schema": { "type": "string", "examples": [ "1752096000" ] } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated `v1,` tokens — several during secret rotation — computed as described under Signature verification.", "schema": { "type": "string", "examples": [ "v1,K5oT8v...base64..." ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Delivery envelope; `data` varies by event type.", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "Event identifier, repeated in the `webhook-id` header.", "examples": [ "whevt_01JXYC5R2K9M" ] }, "type": { "type": "string", "description": "Event type carried by this delivery.", "enum": [ "feedback.received" ], "examples": [ "feedback.received" ] }, "created_at": { "type": "string", "description": "When the event was created.", "examples": [ "2026-07-09T18:25:43.511Z" ] }, "data": { "type": "object", "description": "Reader feedback with the submitter email withheld; resolve `hc_user_id` through the users API if you need contact details.", "required": [ "id", "article_id", "type", "feedback", "hc_user_id" ], "properties": { "id": { "type": "string", "description": "Feedback identifier.", "examples": [ "artfb_01JXY9AZK4KV" ] }, "article_id": { "type": "string", "description": "Article the feedback is about.", "examples": [ "art_01JXY9AZK4KV" ] }, "type": { "type": "string", "description": "Whether the reader found the article helpful.", "examples": [ "positive" ] }, "feedback": { "type": [ "string", "null" ], "description": "Reader’s free text; treat as untrusted.", "examples": [ "This walkthrough was clear and accurate." ] }, "hc_user_id": { "type": [ "string", "null" ], "description": "Help center user matched from the submitter’s email.", "examples": [ "hcusr_01JXYB3S2Y8C" ] } } } } } } } }, "responses": { "2xx": { "description": "Delivery acknowledged; anything else is retried with backoff." } } } }, "task.completed": { "post": { "summary": "Task completed", "description": "Fires when an AI task reaches a terminal status, whether it succeeded or not.", "operationId": "webhookTaskCompleted", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "Envelope `id`, unique per event.", "schema": { "type": "string", "examples": [ "whevt_01JXYC5R2K9M" ] } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when the request was signed; reject stale values.", "schema": { "type": "string", "examples": [ "1752096000" ] } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated `v1,` tokens — several during secret rotation — computed as described under Signature verification.", "schema": { "type": "string", "examples": [ "v1,K5oT8v...base64..." ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Delivery envelope; `data` varies by event type.", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "Event identifier, repeated in the `webhook-id` header.", "examples": [ "whevt_01JXYC5R2K9M" ] }, "type": { "type": "string", "description": "Event type carried by this delivery.", "enum": [ "task.completed" ], "examples": [ "task.completed" ] }, "created_at": { "type": "string", "description": "When the event was created.", "examples": [ "2026-07-09T18:25:43.511Z" ] }, "data": { "type": "object", "required": [ "id", "title", "status", "output_summaries" ], "properties": { "id": { "type": "string", "description": "Task identifier.", "examples": [ "tsk_01JXYAQ4M7RC" ] }, "title": { "type": [ "string", "null" ], "description": "Task title.", "examples": [ "Create API key onboarding docs" ] }, "status": { "type": [ "string", "null" ], "description": "Status the task finished in.", "examples": [ "completed" ] }, "output_summaries": { "type": "array", "description": "Articles the task created or updated.", "items": { "type": "object", "required": [ "id", "url", "title" ], "properties": { "id": { "type": [ "string", "null" ], "description": "Article identifier.", "examples": [ "art_01JXY9AZK4KV" ] }, "url": { "type": [ "string", "null" ], "description": "Public article URL.", "examples": [ "https://docs.example.com/getting-started-api-keys-A1B2C3" ] }, "title": { "type": [ "string", "null" ], "description": "Article title.", "examples": [ "Getting started with API keys" ] } } } } } } } } } } }, "responses": { "2xx": { "description": "Delivery acknowledged; anything else is retried with backoff." } } } } }, "paths": { "/articles": { "post": { "operationId": "createArticle", "tags": [ "Articles" ], "summary": "Create an article", "description": "Creates an article as an open draft. The article is not live until you publish it.\n\n**Required scope:** `content:write`", "responses": { "201": { "description": "Created article", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Article identifier.", "example": "art_01JXY9AZK4KV" }, "title": { "type": "string", "description": "Article title in the default language.", "example": "Getting started with API keys" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL slug used in the public article link.", "example": "getting-started-api-keys" }, "contentHtml": { "description": "Body as HTML, returned when `format=html`.", "example": "

Welcome to the Ferndesk API.

", "type": "string" }, "contentMarkdown": { "description": "Body as Markdown, returned when `format=markdown`.", "example": "# Welcome to the Ferndesk API", "type": "string" }, "contentJson": { "description": "Raw stored Tiptap document, returned when `format=json`.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] }, "anyOf": [ { "description": "Tiptap/ProseMirror document. Image `src` values may be external URLs or `data:` URIs; both are uploaded and rewritten to Ferndesk asset paths on write.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] } }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Canonical public URL of the article.", "example": "https://docs.example.com/getting-started-api-keys-A1B2C3" }, "sectionId": { "anyOf": [ { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, { "type": "null" } ], "description": "Section the article belongs to.", "example": "sect_01JXYA4T1JNT" }, "collectionId": { "anyOf": [ { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, { "type": "null" } ], "description": "Collection grouping the article, when it has one.", "example": "col_01JXYA6ABN52" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publish status.", "example": "published" }, "publishedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "When the article last went live.", "example": "2026-01-15T18:25:43.511Z" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "draft_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Open draft created alongside the article, or null when it was published outright.", "example": "drft_01JXY9AZK4KV" } }, "required": [ "id", "title", "slug", "url", "sectionId", "collectionId", "status", "publishedAt", "createdAt", "updatedAt", "draft_id" ], "description": "The created article and the draft holding its body." } } } }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "429": { "description": "Rate limit exceeded (60 requests per hour per API key). Retry after the number of seconds in the `Retry-After` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Rate limit exceeded" }, "code": { "type": "string", "const": "rate_limited" } }, "required": [ "error", "code" ], "description": "Returned when a request exceeds the global or a per-operation rate limit; a `Retry-After` header carries the seconds to wait." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "Article title.", "example": "Getting started with API keys" }, "content": { "description": "Body as a Tiptap document; not accepted alongside `markdown`.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] } }, "markdown": { "description": "Body as Markdown, converted to rich text on write; not accepted alongside `content`.", "example": "# Getting started\n\nWelcome to the API.", "type": "string" }, "publish": { "default": false, "description": "Publishes the new article in the same call instead of leaving an open draft.", "example": false, "type": "boolean" }, "sectionId": { "type": "string", "minLength": 1, "description": "Section to create the article in.", "example": "sect_01JXYA4T1JNT" }, "collectionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Collection to group the article under.", "example": "col_01JXYA6ABN52" }, "keywords": { "description": "Comma-separated SEO keywords.", "example": "api, auth, keys", "type": "string" }, "metaDescription": { "description": "SEO meta description.", "example": "Learn how to create and rotate Ferndesk API keys.", "type": "string" }, "ogImage": { "description": "Open Graph image URL.", "example": "https://cdn.ferndesk.com/og/getting-started.png", "type": "string" }, "slug": { "description": "Custom URL slug; setting one switches the article to custom-slug mode.", "example": "getting-started-api-keys", "type": "string", "pattern": "^(?=.{2,}$)[a-z0-9]+(?:-[a-z0-9]+)*$" } }, "required": [ "title", "sectionId" ], "description": "New article." } } } } }, "get": { "operationId": "listArticles", "tags": [ "Articles" ], "summary": "List articles", "description": "Returns your help center articles, newest first. Trashed articles are never returned.\n\n**Required scope:** `content:read`", "responses": { "200": { "description": "Cursor-paginated articles", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Article identifier.", "example": "art_01JXY9AZK4KV" }, "title": { "type": "string", "description": "Article title in the default language.", "example": "Getting started with API keys" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL slug used in the public article link.", "example": "getting-started-api-keys" }, "contentHtml": { "description": "Body as HTML, returned when `format=html`.", "example": "

Welcome to the Ferndesk API.

", "type": "string" }, "contentMarkdown": { "description": "Body as Markdown, returned when `format=markdown`.", "example": "# Welcome to the Ferndesk API", "type": "string" }, "contentJson": { "description": "Raw stored Tiptap document, returned when `format=json`.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] }, "anyOf": [ { "description": "Tiptap/ProseMirror document. Image `src` values may be external URLs or `data:` URIs; both are uploaded and rewritten to Ferndesk asset paths on write.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] } }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Canonical public URL of the article.", "example": "https://docs.example.com/getting-started-api-keys-A1B2C3" }, "sectionId": { "anyOf": [ { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, { "type": "null" } ], "description": "Section the article belongs to.", "example": "sect_01JXYA4T1JNT" }, "collectionId": { "anyOf": [ { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, { "type": "null" } ], "description": "Collection grouping the article, when it has one.", "example": "col_01JXYA6ABN52" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publish status.", "example": "published" }, "publishedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "When the article last went live.", "example": "2026-01-15T18:25:43.511Z" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "title", "slug", "url", "sectionId", "collectionId", "status", "publishedAt", "createdAt", "updatedAt" ], "description": "An article and its current body." }, "description": "Items on this page." }, "has_more": { "type": "boolean", "description": "True when further pages follow.", "example": true }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `start_cursor` for the next page; null on the last page.", "example": "eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ" } }, "required": [ "results", "has_more", "next_cursor" ], "description": "One page of results plus the cursor to the next." } } } }, "400": { "description": "Invalid cursor or query", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:read" ], "parameters": [ { "in": "query", "name": "start_cursor", "schema": { "example": "eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ", "type": "string" }, "description": "Opaque cursor taken from the previous response’s `next_cursor`." }, { "in": "query", "name": "page_size", "schema": { "default": 20, "example": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Items per page." }, { "in": "query", "name": "format", "schema": { "default": "html", "example": "markdown", "type": "string", "enum": [ "html", "markdown", "json" ] }, "description": "Which body field to populate: `contentHtml`, `contentMarkdown`, or the lossless `contentJson`." }, { "in": "query", "name": "status", "schema": { "default": "published", "example": "published", "type": "string", "enum": [ "draft", "published", "all" ] }, "description": "Publish status to include; `draft` and `all` need `content:write` and never return trashed articles." }, { "in": "query", "name": "collection_id", "schema": { "example": "col_01JXYA6ABN52", "type": "string" }, "description": "Restricts the list to one collection." }, { "in": "query", "name": "updated_since", "schema": { "example": "2026-01-15T18:25:43.511Z", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": "Returns articles changed at or after this instant, oldest-updated first; ignored once a `start_cursor` carries the ordering." } ] } }, "/articles/{id}": { "patch": { "operationId": "updateArticle", "tags": [ "Articles" ], "summary": "Update an article", "description": "Updates an article. Metadata and placement apply immediately; content edits are staged into an open draft you publish separately.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Updated article", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Article identifier.", "example": "art_01JXY9AZK4KV" }, "title": { "type": "string", "description": "Article title in the default language.", "example": "Getting started with API keys" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL slug used in the public article link.", "example": "getting-started-api-keys" }, "contentHtml": { "description": "Body as HTML, returned when `format=html`.", "example": "

Welcome to the Ferndesk API.

", "type": "string" }, "contentMarkdown": { "description": "Body as Markdown, returned when `format=markdown`.", "example": "# Welcome to the Ferndesk API", "type": "string" }, "contentJson": { "description": "Raw stored Tiptap document, returned when `format=json`.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] }, "anyOf": [ { "description": "Tiptap/ProseMirror document. Image `src` values may be external URLs or `data:` URIs; both are uploaded and rewritten to Ferndesk asset paths on write.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] } }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Canonical public URL of the article.", "example": "https://docs.example.com/getting-started-api-keys-A1B2C3" }, "sectionId": { "anyOf": [ { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, { "type": "null" } ], "description": "Section the article belongs to.", "example": "sect_01JXYA4T1JNT" }, "collectionId": { "anyOf": [ { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, { "type": "null" } ], "description": "Collection grouping the article, when it has one.", "example": "col_01JXYA6ABN52" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publish status.", "example": "published" }, "publishedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "When the article last went live.", "example": "2026-01-15T18:25:43.511Z" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "published": { "type": "boolean", "description": "False when the edit only reached a draft and still needs publishing.", "example": false }, "draft_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Open draft holding the staged content edits.", "example": "drft_01JXY9AZK4KV" }, "message": { "description": "Note explaining what was staged and what was applied.", "example": "Content staged in draft drft_01JXY9AZK4KV; placement applied.", "type": "string" } }, "required": [ "id", "title", "slug", "url", "sectionId", "collectionId", "status", "publishedAt", "createdAt", "updatedAt", "published", "draft_id" ], "description": "The updated article and where each change landed." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope, or the article is managed by an integration and cannot be edited through the API", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Article not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "409": { "description": "Draft conflict: the open draft is owned by a different writer", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "description": "New title, staged into an open draft.", "example": "Getting started with API keys", "type": "string", "minLength": 1 }, "content": { "description": "New body as a Tiptap document, staged into an open draft; not accepted alongside `markdown`.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] } }, "markdown": { "description": "New body as Markdown, staged into an open draft; not accepted alongside `content`.", "example": "# Getting started\n\nWelcome to the API.", "type": "string" }, "collectionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Collection to file the article under, applied immediately.", "example": "col_01JXYA6ABN52" }, "sectionId": { "description": "Section to file the article under, applied immediately.", "example": "sect_01JXYA4T1JNT", "type": "string" }, "keywords": { "description": "Comma-separated SEO keywords.", "example": "api, auth, keys", "type": "string" }, "metaDescription": { "description": "SEO meta description.", "example": "Learn how to create and rotate Ferndesk API keys.", "type": "string" }, "ogImage": { "description": "Open Graph image URL.", "example": "https://cdn.ferndesk.com/og/getting-started.png", "type": "string" }, "listed": { "description": "Where the article may surface: everywhere, by direct link only, nowhere, or to the AI assistant only.", "example": "unlisted", "type": "string", "enum": [ "everywhere", "unlisted", "hidden", "assistant_only" ] }, "noindex": { "description": "Asks search engines to skip the article.", "example": false, "type": "boolean" }, "slug": { "description": "New custom slug; changing it switches the article to custom-slug mode.", "example": "getting-started-api-keys", "type": "string", "pattern": "^(?=.{2,}$)[a-z0-9]+(?:-[a-z0-9]+)*$" } }, "description": "Article changes; content is staged, metadata and placement are immediate." } } } } }, "delete": { "operationId": "trashArticle", "tags": [ "Articles" ], "summary": "Trash an article", "description": "Moves an article to the trash: it leaves public and search surfaces immediately, and stays restorable until it is purged after 30 days.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Trashed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Article identifier.", "example": "art_01JXY9AZK4KV" }, "status": { "type": "string", "const": "trashed" } }, "required": [ "id", "status" ], "description": "The trashed article, restorable until it is purged." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope. Trashing a published article takes live content offline and also requires `content:publish`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Article not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." } ] }, "get": { "operationId": "getArticle", "tags": [ "Articles" ], "summary": "Get an article", "description": "Returns one article. Unpublished articles are visible only to keys that also hold `content:write`.\n\n**Required scope:** `content:read`", "responses": { "200": { "description": "Article", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Article identifier.", "example": "art_01JXY9AZK4KV" }, "title": { "type": "string", "description": "Article title in the default language.", "example": "Getting started with API keys" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL slug used in the public article link.", "example": "getting-started-api-keys" }, "contentHtml": { "description": "Body as HTML, returned when `format=html`.", "example": "

Welcome to the Ferndesk API.

", "type": "string" }, "contentMarkdown": { "description": "Body as Markdown, returned when `format=markdown`.", "example": "# Welcome to the Ferndesk API", "type": "string" }, "contentJson": { "description": "Raw stored Tiptap document, returned when `format=json`.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] }, "anyOf": [ { "description": "Tiptap/ProseMirror document. Image `src` values may be external URLs or `data:` URIs; both are uploaded and rewritten to Ferndesk asset paths on write.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] } }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Canonical public URL of the article.", "example": "https://docs.example.com/getting-started-api-keys-A1B2C3" }, "sectionId": { "anyOf": [ { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, { "type": "null" } ], "description": "Section the article belongs to.", "example": "sect_01JXYA4T1JNT" }, "collectionId": { "anyOf": [ { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, { "type": "null" } ], "description": "Collection grouping the article, when it has one.", "example": "col_01JXYA6ABN52" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publish status.", "example": "published" }, "publishedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "When the article last went live.", "example": "2026-01-15T18:25:43.511Z" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "title", "slug", "url", "sectionId", "collectionId", "status", "publishedAt", "createdAt", "updatedAt" ], "description": "An article and its current body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Article not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:read" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." }, { "in": "query", "name": "format", "schema": { "default": "html", "example": "markdown", "type": "string", "enum": [ "html", "markdown", "json" ] }, "description": "Which body field to populate: `contentHtml`, `contentMarkdown`, or the lossless `contentJson`." } ] } }, "/articles/{id}/publish": { "post": { "operationId": "publishArticle", "tags": [ "Articles" ], "summary": "Publish an article", "description": "Publishes an open draft, making it the live version of the article.\n\n**Required scope:** `content:publish`", "responses": { "200": { "description": "Published", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Article identifier.", "example": "art_01JXY9AZK4KV" }, "status": { "type": "string", "const": "published" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Version number now live.", "example": 4 } }, "required": [ "id", "status", "version" ], "description": "The newly published version." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Article not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "409": { "description": "Draft conflict: `no_draft`, `draft_not_open`, `draft_conflict`, or `draft_outdated` — the latter carries `currentVersion` and `draftBaseVersion` so you can rebase", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:publish" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "draft_id": { "description": "Draft to publish; can be left out only when this key owns exactly one open draft.", "example": "drft_01JXY9AZK4KV", "type": "string" } }, "description": "Draft selection for publishing." } } } } } }, "/articles/{id}/unpublish": { "post": { "operationId": "unpublishArticle", "tags": [ "Articles" ], "summary": "Unpublish an article", "description": "Takes a published article offline and returns it to draft status.\n\n**Required scope:** `content:publish`", "responses": { "200": { "description": "Unpublished", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Article identifier.", "example": "art_01JXY9AZK4KV" }, "status": { "type": "string", "const": "draft" } }, "required": [ "id", "status" ], "description": "The article after being taken offline." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Article not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "409": { "description": "Article is not published", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:publish" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." } ] } }, "/articles/{id}/restore": { "post": { "operationId": "restoreArticle", "tags": [ "Articles" ], "summary": "Restore a trashed article", "description": "Restores a trashed article to the status it had before it was trashed.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Restored", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Article identifier.", "example": "art_01JXY9AZK4KV" }, "status": { "type": "string", "description": "Status the article returned to.", "example": "draft" } }, "required": [ "id", "status" ], "description": "The article after restoring from the trash." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope. Restoring an article that was published brings live content back online and also requires `content:publish`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Article not found or not trashed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." } ] } }, "/articles/{id}/move": { "post": { "operationId": "moveArticle", "tags": [ "Articles" ], "summary": "Move an article", "description": "Moves an article to a different collection or section.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Moved article", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Article identifier.", "example": "art_01JXY9AZK4KV" }, "title": { "type": "string", "description": "Article title in the default language.", "example": "Getting started with API keys" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL slug used in the public article link.", "example": "getting-started-api-keys" }, "contentHtml": { "description": "Body as HTML, returned when `format=html`.", "example": "

Welcome to the Ferndesk API.

", "type": "string" }, "contentMarkdown": { "description": "Body as Markdown, returned when `format=markdown`.", "example": "# Welcome to the Ferndesk API", "type": "string" }, "contentJson": { "description": "Raw stored Tiptap document, returned when `format=json`.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] }, "anyOf": [ { "description": "Tiptap/ProseMirror document. Image `src` values may be external URLs or `data:` URIs; both are uploaded and rewritten to Ferndesk asset paths on write.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] } }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Canonical public URL of the article.", "example": "https://docs.example.com/getting-started-api-keys-A1B2C3" }, "sectionId": { "anyOf": [ { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, { "type": "null" } ], "description": "Section the article belongs to.", "example": "sect_01JXYA4T1JNT" }, "collectionId": { "anyOf": [ { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, { "type": "null" } ], "description": "Collection grouping the article, when it has one.", "example": "col_01JXYA6ABN52" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publish status.", "example": "published" }, "publishedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "When the article last went live.", "example": "2026-01-15T18:25:43.511Z" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "title", "slug", "url", "sectionId", "collectionId", "status", "publishedAt", "createdAt", "updatedAt" ], "description": "An article and its current body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Article not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "collection_id": { "description": "Collection to move into, or null to leave every collection.", "example": "col_01JXYA6ABN52", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "section_id": { "description": "Section to move into.", "example": "sect_01JXYA4T1JNT", "type": "string" } }, "description": "New placement for the article." } } } } } }, "/articles/{id}/drafts": { "get": { "operationId": "listArticleDrafts", "tags": [ "Article drafts" ], "summary": "List article drafts", "description": "Lists the open drafts for an article, across the default language and every translation language.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Drafts", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Draft identifier.", "example": "drft_01JXY9AZK4KV" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Locale being drafted, or null for the default language.", "example": "en" }, "status": { "type": "string", "description": "Draft lifecycle status.", "example": "open" }, "baseVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Article version the draft branched from.", "example": 3 }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Write channel that created the draft.", "example": "api" }, "stale": { "type": "boolean", "description": "True once the article has been published past `baseVersion`.", "example": false }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "language", "status", "baseVersion", "source", "stale", "updatedAt" ], "description": "An open draft, without its body." } } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Article not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." } ] }, "post": { "operationId": "createArticleDraft", "tags": [ "Article drafts" ], "summary": "Create an article draft", "description": "Creates an open draft for an article. Edits stay staged in the draft until it is published.\n\n**Required scope:** `content:write`", "responses": { "201": { "description": "Created draft", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Draft identifier.", "example": "drft_01JXY9AZK4KV" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Locale being drafted, or null for the default language.", "example": "en" }, "status": { "type": "string", "description": "Draft lifecycle status.", "example": "open" }, "baseVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Article version the draft branched from.", "example": 3 }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Write channel that created the draft.", "example": "api" }, "stale": { "type": "boolean", "description": "True once the article has been published past `baseVersion`.", "example": false }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "language", "status", "baseVersion", "source", "stale", "updatedAt" ], "description": "An open draft, without its body." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Article not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "409": { "description": "Draft conflict: an open draft already exists for this language", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "description": "Title to stage.", "example": "Getting started with API keys", "type": "string", "minLength": 1 }, "content": { "description": "Body as a Tiptap document; not accepted alongside `markdown`.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] } }, "markdown": { "description": "Body as Markdown; not accepted alongside `content`.", "example": "# Getting started\n\nWelcome to the API.", "type": "string" }, "language": { "description": "Locale to draft a translation for; omit for the default language.", "example": "fr", "type": "string", "minLength": 2, "maxLength": 16 } }, "description": "New draft." } } } } } }, "/articles/{id}/drafts/{draftId}": { "get": { "operationId": "getArticleDraft", "tags": [ "Article drafts" ], "summary": "Get an article draft", "description": "Returns one draft with the content staged in it.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Draft", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Draft identifier.", "example": "drft_01JXY9AZK4KV" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Locale being drafted, or null for the default language.", "example": "en" }, "status": { "type": "string", "description": "Draft lifecycle status.", "example": "open" }, "baseVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Article version the draft branched from.", "example": 3 }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Write channel that created the draft.", "example": "api" }, "stale": { "type": "boolean", "description": "True once the article has been published past `baseVersion`.", "example": false }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Title staged in the draft.", "example": "Getting started with API keys" }, "contentHtml": { "description": "Staged body as HTML, returned when `format=html`.", "example": "

Welcome to the Ferndesk API.

", "type": "string" }, "contentMarkdown": { "description": "Staged body as Markdown, returned when `format=markdown`.", "example": "# Welcome to the Ferndesk API", "type": "string" }, "contentJson": { "description": "Raw stored Tiptap document, returned when `format=json`.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] }, "anyOf": [ { "description": "Tiptap/ProseMirror document. Image `src` values may be external URLs or `data:` URIs; both are uploaded and rewritten to Ferndesk asset paths on write.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] } }, { "type": "null" } ] } }, "required": [ "id", "language", "status", "baseVersion", "source", "stale", "updatedAt", "title" ], "description": "An open draft and the body staged in it." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Draft not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Article identifier." }, { "in": "path", "name": "draftId", "schema": { "type": "string", "example": "drft_01JXY9AZK4KV" }, "required": true, "description": "Draft identifier." }, { "in": "query", "name": "format", "schema": { "default": "html", "example": "markdown", "type": "string", "enum": [ "html", "markdown", "json" ] }, "description": "Which body field to populate: `contentHtml`, `contentMarkdown`, or the lossless `contentJson`." } ] }, "patch": { "operationId": "updateArticleDraft", "tags": [ "Article drafts" ], "summary": "Update an article draft", "description": "Updates the title and content staged in an open draft.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Updated draft", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Draft identifier.", "example": "drft_01JXY9AZK4KV" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Locale being drafted, or null for the default language.", "example": "en" }, "status": { "type": "string", "description": "Draft lifecycle status.", "example": "open" }, "baseVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Article version the draft branched from.", "example": 3 }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Write channel that created the draft.", "example": "api" }, "stale": { "type": "boolean", "description": "True once the article has been published past `baseVersion`.", "example": false }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "language", "status", "baseVersion", "source", "stale", "updatedAt" ], "description": "An open draft, without its body." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Draft not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "409": { "description": "Draft conflict: the draft is owned by a different writer", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Article identifier." }, { "in": "path", "name": "draftId", "schema": { "type": "string", "example": "drft_01JXY9AZK4KV" }, "required": true, "description": "Draft identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "content": { "description": "Tiptap/ProseMirror document. Image `src` values may be external URLs or `data:` URIs; both are uploaded and rewritten to Ferndesk asset paths on write.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] } }, "markdown": { "type": "string" } }, "description": "Draft changes." } } } } } }, "/articles/{id}/revisions": { "get": { "operationId": "listArticleRevisions", "tags": [ "Article revisions" ], "summary": "List article revisions", "description": "Lists an article’s version history, newest first. A new revision is captured on every publish.\n\n**Required scope:** `content:read`", "responses": { "200": { "description": "Revisions", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Revision identifier.", "example": "rev_01JXY9AZK4KV" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Version this revision captured.", "example": 3 }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Title at the time of the publish.", "example": "Getting started with API keys" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Write channel that published it.", "example": "api" }, "comment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Note left with the publish.", "example": "Clarified the key rotation steps." }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "version", "title", "source", "comment", "createdAt" ], "description": "One entry in an article’s version history." }, "description": "Items on this page." }, "has_more": { "type": "boolean", "description": "True when further pages follow.", "example": true }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `start_cursor` for the next page; null on the last page.", "example": "eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ" } }, "required": [ "results", "has_more", "next_cursor" ], "description": "One page of results plus the cursor to the next." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Article not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:read" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." } ] } }, "/articles/{id}/revisions/{revisionId}": { "get": { "operationId": "getArticleRevision", "tags": [ "Article revisions" ], "summary": "Get an article revision", "description": "Returns the content snapshot captured in one revision of an article.\n\n**Required scope:** `content:read`", "responses": { "200": { "description": "Revision", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Revision identifier.", "example": "rev_01JXY9AZK4KV" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Version this revision captured.", "example": 3 }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Title at the time of the publish.", "example": "Getting started with API keys" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Write channel that published it.", "example": "api" }, "comment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Note left with the publish.", "example": "Clarified the key rotation steps." }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "language": { "type": "string", "description": "Locale this revision belongs to.", "example": "en" }, "contentHtml": { "description": "Snapshot body as HTML, returned when `format=html`.", "example": "

Welcome to the Ferndesk API.

", "type": "string" }, "contentMarkdown": { "description": "Snapshot body as Markdown, returned when `format=markdown`.", "example": "# Welcome to the Ferndesk API", "type": "string" }, "contentJson": { "description": "Raw stored Tiptap document, returned when `format=json`.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] }, "anyOf": [ { "description": "Tiptap/ProseMirror document. Image `src` values may be external URLs or `data:` URIs; both are uploaded and rewritten to Ferndesk asset paths on write.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] } }, { "type": "null" } ] } }, "required": [ "id", "version", "title", "source", "comment", "createdAt", "language" ], "description": "A revision and the body it captured." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Revision not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:read" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Article identifier." }, { "in": "path", "name": "revisionId", "schema": { "type": "string", "example": "rev_01JXY9AZK4KV" }, "required": true, "description": "Revision identifier." }, { "in": "query", "name": "format", "schema": { "default": "html", "example": "markdown", "type": "string", "enum": [ "html", "markdown", "json" ] }, "description": "Which body field to populate: `contentHtml`, `contentMarkdown`, or the lossless `contentJson`." } ] } }, "/articles/{id}/revisions/{revisionId}/restore": { "post": { "operationId": "restoreArticleRevision", "tags": [ "Article revisions" ], "summary": "Restore an article revision", "description": "Restores an old revision by staging it as a new draft and publishing it on top of the current version, so history stays linear.\n\n**Required scope:** `content:publish`", "responses": { "200": { "description": "Restored", "content": { "application/json": { "schema": { "type": "object", "properties": { "articleId": { "type": "string", "description": "Article that was restored.", "example": "art_01JXY9AZK4KV" }, "language": { "type": "string", "description": "Locale of the restored revision.", "example": "en" }, "restoredFromVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Version the content came from.", "example": 3 }, "newVersion": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Version the restore published, or null for a translation restore.", "example": 5 } }, "required": [ "articleId", "language", "restoredFromVersion", "newVersion" ], "description": "The version the restore produced." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Revision not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "409": { "description": "Draft conflict: another open draft blocks the restore", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:publish" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Article identifier." }, { "in": "path", "name": "revisionId", "schema": { "type": "string", "example": "rev_01JXY9AZK4KV" }, "required": true, "description": "Revision identifier." } ] } }, "/articles/{id}/revisions/{revisionId}/diff": { "get": { "operationId": "diffArticleRevisions", "tags": [ "Article revisions" ], "summary": "Diff two revisions", "description": "Returns a unified Markdown line diff between two revisions of an article.\n\n**Required scope:** `content:read`", "responses": { "200": { "description": "Diff", "content": { "application/json": { "schema": { "type": "object", "properties": { "articleId": { "type": "string", "description": "Article identifier.", "example": "art_01JXY9AZK4KV" }, "from": { "type": "object", "properties": { "revisionId": { "type": "string", "example": "rev_01JXY9AZK4KV" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "example": 3 } }, "required": [ "revisionId", "version" ], "description": "Older side of the comparison." }, "to": { "type": "object", "properties": { "revisionId": { "type": "string", "example": "rev_01JXYB7Q2N4D" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "example": 4 } }, "required": [ "revisionId", "version" ], "description": "Newer side of the comparison." }, "changed": { "type": "boolean", "description": "False when the bodies are identical.", "example": true }, "diff": { "type": "string", "description": "Unified-style Markdown line diff.", "example": "- Old line\n+ New line" }, "addedLines": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Lines added.", "example": 12 }, "removedLines": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Lines removed.", "example": 4 }, "truncated": { "type": "boolean", "description": "True when the diff was cut short for size.", "example": false } }, "required": [ "articleId", "from", "to", "changed", "diff", "addedLines", "removedLines", "truncated" ], "description": "Line-level differences between two revisions." } } } }, "400": { "description": "Invalid `against`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Revision not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:read" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Article identifier." }, { "in": "path", "name": "revisionId", "schema": { "type": "string", "example": "rev_01JXY9AZK4KV" }, "required": true, "description": "Revision identifier." }, { "in": "query", "name": "against", "schema": { "type": "string", "example": "3" }, "required": true, "description": "Version number or revision id to compare against." } ] } }, "/articles/languages": { "get": { "operationId": "listHelpdeskLanguages", "tags": [ "Article translations" ], "summary": "List help center languages", "description": "Returns the default language and every translation language configured for your help center.\n\n**Required scope:** `content:read`", "responses": { "200": { "description": "Languages", "content": { "application/json": { "schema": { "type": "object", "properties": { "default": { "type": "string", "description": "Locale articles are authored in.", "example": "en" }, "languages": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string", "description": "Locale.", "example": "fr" }, "displayName": { "type": "string", "description": "Name shown in the language picker.", "example": "Français" }, "isDefault": { "type": "boolean", "description": "True for the authoring locale.", "example": false }, "isEnabled": { "type": "boolean", "description": "False while a locale is configured but switched off.", "example": true } }, "required": [ "language", "displayName", "isDefault", "isEnabled" ] }, "description": "Every configured locale, including the default." } }, "required": [ "default", "languages" ], "description": "Languages configured for the help center." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:read" ] } }, "/articles/translations/missing": { "get": { "operationId": "listArticlesMissingTranslations", "tags": [ "Article translations" ], "summary": "List articles missing translations", "description": "Returns the published article IDs that have no translation yet, grouped by locale.\n\n**Required scope:** `content:read`", "responses": { "200": { "description": "Missing translations", "content": { "application/json": { "schema": { "type": "object", "properties": { "missing": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "missing" ] } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:read" ], "parameters": [ { "in": "query", "name": "locales", "schema": { "example": "fr,es", "type": "string" }, "description": "Comma-separated locales to check; defaults to every enabled translation language." } ] } }, "/articles/{id}/translations": { "get": { "operationId": "listArticleTranslations", "tags": [ "Article translations" ], "summary": "List article translations", "description": "Returns the translation status of an article for every locale.\n\n**Required scope:** `content:read`", "responses": { "200": { "description": "Translations", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string", "description": "Locale.", "example": "fr" }, "status": { "type": "string", "description": "Translation status.", "example": "translated" }, "isManual": { "type": "boolean", "description": "True when a human supplied the translation rather than Fern.", "example": false }, "sourceArticleVersion": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Default-language version this translation was made from.", "example": 3 }, "stale": { "type": "boolean", "description": "True once the default-language article has moved past `sourceArticleVersion`.", "example": false }, "updatedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ] } }, "required": [ "language", "status", "isManual", "sourceArticleVersion", "stale", "updatedAt" ], "description": "Translation coverage for one locale." } } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Article not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:read" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." } ] } }, "/articles/{id}/translations/{locale}": { "get": { "operationId": "getArticleTranslation", "tags": [ "Article translations" ], "summary": "Get an article translation", "description": "Returns the localized version of an article for one locale.\n\n**Required scope:** `content:read`", "responses": { "200": { "description": "Article translation", "content": { "application/json": { "schema": { "type": "object", "properties": { "articleId": { "type": "string", "description": "Article identifier.", "example": "art_01JXY9AZK4KV" }, "language": { "type": "string", "description": "Locale of this translation.", "example": "fr" }, "title": { "type": "string", "description": "Localized article title.", "example": "Débuter avec les clés API" }, "contentHtml": { "description": "Localized body as HTML, returned when `format=html`.", "example": "

Découvrez le fonctionnement des clés API.

", "type": "string" }, "contentMarkdown": { "description": "Localized body as Markdown, returned when `format=markdown`.", "example": "# Découvrez le fonctionnement des clés API", "type": "string" }, "contentJson": { "description": "Raw stored Tiptap document, returned when `format=json`.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] }, "anyOf": [ { "description": "Tiptap/ProseMirror document. Image `src` values may be external URLs or `data:` URIs; both are uploaded and rewritten to Ferndesk asset paths on write.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] } }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Canonical public URL of the translated article.", "example": "https://docs.example.com/fr/getting-started-api-keys-A1B2C3" }, "status": { "type": "string", "description": "Translation lifecycle status.", "example": "published" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "articleId", "language", "title", "url", "status", "updatedAt" ], "description": "An article rendered in one locale." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Translation not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:read" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." }, { "in": "path", "name": "locale", "schema": { "type": "string", "minLength": 2, "maxLength": 16, "example": "en" }, "required": true, "description": "Locale code of the translation." }, { "in": "query", "name": "format", "schema": { "default": "html", "example": "markdown", "type": "string", "enum": [ "html", "markdown", "json" ] }, "description": "Which body field to populate: `contentHtml`, `contentMarkdown`, or the lossless `contentJson`." } ] }, "put": { "operationId": "putArticleTranslation", "tags": [ "Article translations" ], "summary": "Create or update a translation", "description": "Stages a translation draft for a locale, creating the translation if it does not exist yet.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Staged/published translation", "content": { "application/json": { "schema": { "type": "object", "properties": { "articleId": { "type": "string", "description": "Article the translation belongs to.", "example": "art_01JXY9AZK4KV" }, "language": { "type": "string", "description": "Locale.", "example": "fr" }, "draftId": { "type": "string", "description": "Draft holding the staged translation.", "example": "drft_01JXY9AZK4KV" }, "published": { "type": "boolean", "description": "False when the translation was staged but not published.", "example": false } }, "required": [ "articleId", "language", "draftId", "published" ], "description": "Where the translation landed." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Article not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "409": { "description": "Draft conflict: an open translation draft is owned by a different writer", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." }, { "in": "path", "name": "locale", "schema": { "type": "string", "minLength": 2, "maxLength": 16, "example": "en" }, "required": true, "description": "Locale code of the translation." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "description": "Localized title.", "example": "Débuter avec les clés API", "type": "string", "minLength": 1 }, "content": { "description": "Localized body as a Tiptap document; not accepted alongside `markdown`.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] } }, "markdown": { "description": "Localized body as Markdown; not accepted alongside `content`.", "example": "# Débuter\n\nBienvenue dans l’API.", "type": "string" }, "publish": { "default": false, "description": "Publishes the translation in the same call instead of leaving it staged.", "example": false, "type": "boolean" } }, "description": "Translation to stage for a locale." } } } } } }, "/articles/incremental": { "get": { "operationId": "exportArticlesIncremental", "tags": [ "Articles" ], "summary": "Export articles incrementally", "description": "A sync feed of every article, ordered oldest `updated_at` first so a consumer can resume where it stopped.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Cursor-paginated page of articles in every status — draft, published, unpublished, and trashed — each carrying its current `status`, so a downstream mirror sees deletions and unpublishes as status changes rather than rows vanishing", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Article identifier.", "example": "art_01JXY9AZK4KV" }, "title": { "type": "string", "description": "Article title in the default language.", "example": "Getting started with API keys" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL slug used in the public article link.", "example": "getting-started-api-keys" }, "contentHtml": { "description": "Body as HTML, returned when `format=html`.", "example": "

Welcome to the Ferndesk API.

", "type": "string" }, "contentMarkdown": { "description": "Body as Markdown, returned when `format=markdown`.", "example": "# Welcome to the Ferndesk API", "type": "string" }, "contentJson": { "description": "Raw stored Tiptap document, returned when `format=json`.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] }, "anyOf": [ { "description": "Tiptap/ProseMirror document. Image `src` values may be external URLs or `data:` URIs; both are uploaded and rewritten to Ferndesk asset paths on write.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] } }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Canonical public URL of the article.", "example": "https://docs.example.com/getting-started-api-keys-A1B2C3" }, "sectionId": { "anyOf": [ { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, { "type": "null" } ], "description": "Section the article belongs to.", "example": "sect_01JXYA4T1JNT" }, "collectionId": { "anyOf": [ { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, { "type": "null" } ], "description": "Collection grouping the article, when it has one.", "example": "col_01JXYA6ABN52" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publish status.", "example": "published" }, "publishedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "When the article last went live.", "example": "2026-01-15T18:25:43.511Z" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "title", "slug", "url", "sectionId", "collectionId", "status", "publishedAt", "createdAt", "updatedAt" ], "description": "An article and its current body." }, "description": "Items on this page." }, "has_more": { "type": "boolean", "description": "True when further pages follow.", "example": true }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `start_cursor` for the next page; null on the last page.", "example": "eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ" } }, "required": [ "results", "has_more", "next_cursor" ], "description": "One page of results plus the cursor to the next." } } } }, "400": { "description": "Missing `since` on the first request, or invalid cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "query", "name": "start_cursor", "schema": { "example": "eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ", "type": "string" }, "description": "Opaque cursor taken from the previous response’s `next_cursor`." }, { "in": "query", "name": "page_size", "schema": { "default": 20, "example": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Items per page." }, { "in": "query", "name": "since", "schema": { "example": "2026-01-15T18:25:43.511Z", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": "Inclusive lower bound on `updated_at`; required on the first request, then replaced by `start_cursor`." }, { "in": "query", "name": "format", "schema": { "default": "html", "example": "markdown", "type": "string", "enum": [ "html", "markdown", "json" ] }, "description": "Which body field to populate: `contentHtml`, `contentMarkdown`, or the lossless `contentJson`." } ] } }, "/articles/search": { "get": { "operationId": "searchArticles", "tags": [ "Articles" ], "summary": "Search articles", "description": "Full-text search across your published articles. Ranking replaces pagination, so `next_cursor` is always null.\n\n**Required scope:** `content:read`", "responses": { "200": { "description": "Relevance-ranked articles", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Article identifier.", "example": "art_01JXY9AZK4KV" }, "title": { "type": "string", "description": "Article title in the default language.", "example": "Getting started with API keys" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL slug used in the public article link.", "example": "getting-started-api-keys" }, "contentHtml": { "description": "Body as HTML, returned when `format=html`.", "example": "

Welcome to the Ferndesk API.

", "type": "string" }, "contentMarkdown": { "description": "Body as Markdown, returned when `format=markdown`.", "example": "# Welcome to the Ferndesk API", "type": "string" }, "contentJson": { "description": "Raw stored Tiptap document, returned when `format=json`.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] }, "anyOf": [ { "description": "Tiptap/ProseMirror document. Image `src` values may be external URLs or `data:` URIs; both are uploaded and rewritten to Ferndesk asset paths on write.", "example": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Welcome to Ferndesk." } ] } ] } }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Canonical public URL of the article.", "example": "https://docs.example.com/getting-started-api-keys-A1B2C3" }, "sectionId": { "anyOf": [ { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, { "type": "null" } ], "description": "Section the article belongs to.", "example": "sect_01JXYA4T1JNT" }, "collectionId": { "anyOf": [ { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, { "type": "null" } ], "description": "Collection grouping the article, when it has one.", "example": "col_01JXYA6ABN52" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publish status.", "example": "published" }, "publishedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "When the article last went live.", "example": "2026-01-15T18:25:43.511Z" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "title", "slug", "url", "sectionId", "collectionId", "status", "publishedAt", "createdAt", "updatedAt" ], "description": "An article and its current body." }, "description": "Items on this page." }, "has_more": { "type": "boolean", "description": "True when further pages follow.", "example": true }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `start_cursor` for the next page; null on the last page.", "example": "eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ" } }, "required": [ "results", "has_more", "next_cursor" ], "description": "One page of results plus the cursor to the next." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:read" ], "parameters": [ { "in": "query", "name": "query", "schema": { "type": "string", "minLength": 1, "example": "authentication" }, "required": true, "description": "Text to search for." }, { "in": "query", "name": "page_size", "schema": { "default": 20, "example": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Ranked results to return; search ranks at most 100 matches, and `has_more` reports when that ceiling is hit." }, { "in": "query", "name": "format", "schema": { "default": "html", "example": "markdown", "type": "string", "enum": [ "html", "markdown", "json" ] }, "description": "Which body field to populate: `contentHtml`, `contentMarkdown`, or the lossless `contentJson`." } ] } }, "/collections": { "get": { "operationId": "listCollections", "tags": [ "Collections" ], "summary": "List collections", "description": "Returns the collections in your help center, newest first.\n\n**Required scope:** `content:read`", "responses": { "200": { "description": "Cursor-paginated collections", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, "helpdeskId": { "type": "string", "description": "Help center identifier.", "example": "help_01JXYA7B3T7G" }, "sectionId": { "anyOf": [ { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, { "type": "null" } ], "description": "Section this collection sits in.", "example": "sect_01JXYA4T1JNT" }, "parentCollectionId": { "anyOf": [ { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, { "type": "null" } ], "description": "Collection this one is nested under, or null at the root.", "example": null }, "title": { "type": "string", "description": "Collection title.", "example": "Authentication" }, "subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Supporting line shown under the collection title.", "example": "API key and token flows" }, "shortId": { "type": "string", "description": "Short human-friendly identifier used in public URLs.", "example": "C0L123" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "translations": { "default": [], "description": "One entry per translated locale.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Translation record identifier.", "example": "coltr_01JXYA6ABN52" }, "collectionId": { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, "language": { "type": "string", "description": "Locale of this translation.", "example": "fr" }, "title": { "type": "string", "description": "Localized collection title.", "example": "Authentification" }, "subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Localized supporting line.", "example": "Clés API et jetons" }, "status": { "type": "string", "description": "Translation status.", "example": "published" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "collectionId", "language", "title", "subtitle", "status", "createdAt", "updatedAt" ] } } }, "required": [ "id", "helpdeskId", "sectionId", "parentCollectionId", "title", "subtitle", "shortId", "createdAt", "updatedAt" ], "description": "A collection of related articles." }, "description": "Items on this page." }, "has_more": { "type": "boolean", "description": "True when further pages follow.", "example": true }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `start_cursor` for the next page; null on the last page.", "example": "eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ" } }, "required": [ "results", "has_more", "next_cursor" ], "description": "One page of results plus the cursor to the next." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:read" ], "parameters": [ { "in": "query", "name": "start_cursor", "schema": { "example": "eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ", "type": "string" }, "description": "Opaque cursor taken from the previous response’s `next_cursor`." }, { "in": "query", "name": "page_size", "schema": { "default": 20, "example": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Items per page." } ] }, "post": { "operationId": "createCollection", "tags": [ "Collections" ], "summary": "Create a collection", "description": "Creates a collection, the grouping that holds related articles inside a section.\n\n**Required scope:** `content:write`", "responses": { "201": { "description": "Created collection", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, "helpdeskId": { "type": "string", "description": "Help center identifier.", "example": "help_01JXYA7B3T7G" }, "sectionId": { "anyOf": [ { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, { "type": "null" } ], "description": "Section this collection sits in.", "example": "sect_01JXYA4T1JNT" }, "parentCollectionId": { "anyOf": [ { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, { "type": "null" } ], "description": "Collection this one is nested under, or null at the root.", "example": null }, "title": { "type": "string", "description": "Collection title.", "example": "Authentication" }, "subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Supporting line shown under the collection title.", "example": "API key and token flows" }, "shortId": { "type": "string", "description": "Short human-friendly identifier used in public URLs.", "example": "C0L123" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "translations": { "default": [], "description": "One entry per translated locale.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Translation record identifier.", "example": "coltr_01JXYA6ABN52" }, "collectionId": { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, "language": { "type": "string", "description": "Locale of this translation.", "example": "fr" }, "title": { "type": "string", "description": "Localized collection title.", "example": "Authentification" }, "subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Localized supporting line.", "example": "Clés API et jetons" }, "status": { "type": "string", "description": "Translation status.", "example": "published" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "collectionId", "language", "title", "subtitle", "status", "createdAt", "updatedAt" ] } } }, "required": [ "id", "helpdeskId", "sectionId", "parentCollectionId", "title", "subtitle", "shortId", "createdAt", "updatedAt" ], "description": "A collection of related articles." } } } }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "Collection title.", "example": "Authentication" }, "subtitle": { "description": "Supporting line shown under the title.", "example": "API key and token flows", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sectionId": { "type": "string", "minLength": 1, "description": "Section to create the collection in.", "example": "sect_01JXYA4T1JNT" }, "parentCollectionId": { "description": "Collection to nest this one under.", "example": "col_01JXYA6ABN52", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title", "sectionId" ], "description": "New collection." } } } } } }, "/collections/{id}": { "get": { "operationId": "getCollection", "tags": [ "Collections" ], "summary": "Get a collection", "description": "Returns one collection with its translations.\n\n**Required scope:** `content:read`", "responses": { "200": { "description": "Collection", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, "helpdeskId": { "type": "string", "description": "Help center identifier.", "example": "help_01JXYA7B3T7G" }, "sectionId": { "anyOf": [ { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, { "type": "null" } ], "description": "Section this collection sits in.", "example": "sect_01JXYA4T1JNT" }, "parentCollectionId": { "anyOf": [ { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, { "type": "null" } ], "description": "Collection this one is nested under, or null at the root.", "example": null }, "title": { "type": "string", "description": "Collection title.", "example": "Authentication" }, "subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Supporting line shown under the collection title.", "example": "API key and token flows" }, "shortId": { "type": "string", "description": "Short human-friendly identifier used in public URLs.", "example": "C0L123" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "translations": { "default": [], "description": "One entry per translated locale.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Translation record identifier.", "example": "coltr_01JXYA6ABN52" }, "collectionId": { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, "language": { "type": "string", "description": "Locale of this translation.", "example": "fr" }, "title": { "type": "string", "description": "Localized collection title.", "example": "Authentification" }, "subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Localized supporting line.", "example": "Clés API et jetons" }, "status": { "type": "string", "description": "Translation status.", "example": "published" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "collectionId", "language", "title", "subtitle", "status", "createdAt", "updatedAt" ] } } }, "required": [ "id", "helpdeskId", "sectionId", "parentCollectionId", "title", "subtitle", "shortId", "createdAt", "updatedAt" ], "description": "A collection of related articles." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:read" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." } ] }, "patch": { "operationId": "updateCollection", "tags": [ "Collections" ], "summary": "Update a collection", "description": "Updates a collection’s wording or its position in the help center navigation.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Updated collection", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, "helpdeskId": { "type": "string", "description": "Help center identifier.", "example": "help_01JXYA7B3T7G" }, "sectionId": { "anyOf": [ { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, { "type": "null" } ], "description": "Section this collection sits in.", "example": "sect_01JXYA4T1JNT" }, "parentCollectionId": { "anyOf": [ { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, { "type": "null" } ], "description": "Collection this one is nested under, or null at the root.", "example": null }, "title": { "type": "string", "description": "Collection title.", "example": "Authentication" }, "subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Supporting line shown under the collection title.", "example": "API key and token flows" }, "shortId": { "type": "string", "description": "Short human-friendly identifier used in public URLs.", "example": "C0L123" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "translations": { "default": [], "description": "One entry per translated locale.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Translation record identifier.", "example": "coltr_01JXYA6ABN52" }, "collectionId": { "type": "string", "description": "Collection identifier.", "example": "col_01JXYA6ABN52" }, "language": { "type": "string", "description": "Locale of this translation.", "example": "fr" }, "title": { "type": "string", "description": "Localized collection title.", "example": "Authentification" }, "subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Localized supporting line.", "example": "Clés API et jetons" }, "status": { "type": "string", "description": "Translation status.", "example": "published" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "collectionId", "language", "title", "subtitle", "status", "createdAt", "updatedAt" ] } } }, "required": [ "id", "helpdeskId", "sectionId", "parentCollectionId", "title", "subtitle", "shortId", "createdAt", "updatedAt" ], "description": "A collection of related articles." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "description": "New collection title.", "example": "Authentication", "type": "string", "minLength": 1 }, "subtitle": { "description": "New supporting line, or null to clear it.", "example": "API key and token flows", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sectionId": { "description": "Section to move the collection into.", "example": "sect_01JXYA4T1JNT", "type": "string" }, "parentCollectionId": { "description": "Collection to nest under, or null to move it to the root.", "example": "col_01JXYA6ABN52", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "description": "Collection changes." } } } } }, "delete": { "operationId": "deleteCollection", "tags": [ "Collections" ], "summary": "Delete a collection", "description": "Deletes a collection and moves every article inside it to the trash, where each can still be restored individually.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the deleted resource.", "example": "col_01JXYA6ABN52" }, "deleted": { "type": "boolean", "const": true, "description": "Always true on a successful delete.", "example": true } }, "required": [ "id", "deleted" ] } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope. Deleting a collection that holds published articles takes live content offline and also requires `content:publish`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." } ] } }, "/sections": { "get": { "operationId": "listSections", "tags": [ "Sections" ], "summary": "List sections", "description": "Returns the sections in your help center, ordered by display position.\n\n**Required scope:** `content:read`", "responses": { "200": { "description": "Cursor-paginated sections", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, "helpdeskId": { "type": "string", "description": "Help center identifier.", "example": "help_01JXYA7B3T7G" }, "name": { "type": "string", "description": "Section display name.", "example": "Guides" }, "isDefault": { "type": "boolean", "description": "True for the help center’s default section, which cannot be deleted.", "example": false }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sort position in the navigation.", "example": 1 }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "translations": { "default": [], "description": "One entry per translated locale.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Translation record identifier.", "example": "secttr_01JXYA4T1JNT" }, "sectionId": { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, "language": { "type": "string", "description": "Locale of this translation.", "example": "fr" }, "name": { "type": "string", "description": "Localized section name.", "example": "Guides" }, "status": { "type": "string", "description": "Translation status.", "example": "published" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "sectionId", "language", "name", "status", "createdAt", "updatedAt" ] } } }, "required": [ "id", "helpdeskId", "name", "isDefault", "position", "createdAt", "updatedAt" ], "description": "A top-level section of the help center navigation." }, "description": "Items on this page." }, "has_more": { "type": "boolean", "description": "True when further pages follow.", "example": true }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `start_cursor` for the next page; null on the last page.", "example": "eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ" } }, "required": [ "results", "has_more", "next_cursor" ], "description": "One page of results plus the cursor to the next." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:read" ], "parameters": [ { "in": "query", "name": "start_cursor", "schema": { "example": "eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ", "type": "string" }, "description": "Opaque cursor taken from the previous response’s `next_cursor`." }, { "in": "query", "name": "page_size", "schema": { "default": 20, "example": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Items per page." } ] }, "post": { "operationId": "createSection", "tags": [ "Sections" ], "summary": "Create a section", "description": "Creates a top-level section in your help center navigation.\n\n**Required scope:** `content:write`", "responses": { "201": { "description": "Created section", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, "helpdeskId": { "type": "string", "description": "Help center identifier.", "example": "help_01JXYA7B3T7G" }, "name": { "type": "string", "description": "Section display name.", "example": "Guides" }, "isDefault": { "type": "boolean", "description": "True for the help center’s default section, which cannot be deleted.", "example": false }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sort position in the navigation.", "example": 1 }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "translations": { "default": [], "description": "One entry per translated locale.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Translation record identifier.", "example": "secttr_01JXYA4T1JNT" }, "sectionId": { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, "language": { "type": "string", "description": "Locale of this translation.", "example": "fr" }, "name": { "type": "string", "description": "Localized section name.", "example": "Guides" }, "status": { "type": "string", "description": "Translation status.", "example": "published" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "sectionId", "language", "name", "status", "createdAt", "updatedAt" ] } } }, "required": [ "id", "helpdeskId", "name", "isDefault", "position", "createdAt", "updatedAt" ], "description": "A top-level section of the help center navigation." } } } }, "400": { "description": "Invalid slug", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Section name.", "example": "Guides" }, "slug": { "description": "URL slug; derived from the name when omitted.", "example": "guides", "type": "string", "minLength": 1 } }, "required": [ "name" ], "description": "New section." } } } } } }, "/sections/{id}": { "get": { "operationId": "getSection", "tags": [ "Sections" ], "summary": "Get a section", "description": "Returns one section with its translations.\n\n**Required scope:** `content:read`", "responses": { "200": { "description": "Section", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, "helpdeskId": { "type": "string", "description": "Help center identifier.", "example": "help_01JXYA7B3T7G" }, "name": { "type": "string", "description": "Section display name.", "example": "Guides" }, "isDefault": { "type": "boolean", "description": "True for the help center’s default section, which cannot be deleted.", "example": false }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sort position in the navigation.", "example": 1 }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "translations": { "default": [], "description": "One entry per translated locale.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Translation record identifier.", "example": "secttr_01JXYA4T1JNT" }, "sectionId": { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, "language": { "type": "string", "description": "Locale of this translation.", "example": "fr" }, "name": { "type": "string", "description": "Localized section name.", "example": "Guides" }, "status": { "type": "string", "description": "Translation status.", "example": "published" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "sectionId", "language", "name", "status", "createdAt", "updatedAt" ] } } }, "required": [ "id", "helpdeskId", "name", "isDefault", "position", "createdAt", "updatedAt" ], "description": "A top-level section of the help center navigation." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Section not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:read" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." } ] }, "patch": { "operationId": "updateSection", "tags": [ "Sections" ], "summary": "Update a section", "description": "Updates a section, the top-level grouping in your help center navigation.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Updated section", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, "helpdeskId": { "type": "string", "description": "Help center identifier.", "example": "help_01JXYA7B3T7G" }, "name": { "type": "string", "description": "Section display name.", "example": "Guides" }, "isDefault": { "type": "boolean", "description": "True for the help center’s default section, which cannot be deleted.", "example": false }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sort position in the navigation.", "example": 1 }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "translations": { "default": [], "description": "One entry per translated locale.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Translation record identifier.", "example": "secttr_01JXYA4T1JNT" }, "sectionId": { "type": "string", "description": "Section identifier.", "example": "sect_01JXYA4T1JNT" }, "language": { "type": "string", "description": "Locale of this translation.", "example": "fr" }, "name": { "type": "string", "description": "Localized section name.", "example": "Guides" }, "status": { "type": "string", "description": "Translation status.", "example": "published" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "sectionId", "language", "name", "status", "createdAt", "updatedAt" ] } } }, "required": [ "id", "helpdeskId", "name", "isDefault", "position", "createdAt", "updatedAt" ], "description": "A top-level section of the help center navigation." } } } }, "400": { "description": "Invalid slug", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Section not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "New section name.", "example": "Guides", "type": "string", "minLength": 1 }, "slug": { "description": "New URL slug.", "example": "guides", "type": "string" } }, "description": "Section changes." } } } } }, "delete": { "operationId": "deleteSection", "tags": [ "Sections" ], "summary": "Delete a section", "description": "Deletes a section. Only an empty section that is neither the default nor the last one can be deleted.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the deleted resource.", "example": "col_01JXYA6ABN52" }, "deleted": { "type": "boolean", "const": true, "description": "Always true on a successful delete.", "example": true } }, "required": [ "id", "deleted" ] } } } }, "400": { "description": "Section is not empty", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Section not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "409": { "description": "Section is the default or the last remaining section", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." } ] } }, "/users": { "get": { "operationId": "listHelpCenterUsers", "tags": [ "Users" ], "summary": "List help center users", "description": "Returns your help center users, newest first.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Cursor-paginated help center users", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Help center user identifier.", "example": "hcusr_01JXYB3S2Y8C" }, "helpdeskId": { "type": "string", "description": "Help center identifier.", "example": "help_01JXYA7B3T7G" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Email address, stored lowercase.", "example": "alice@example.com" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name.", "example": "Alice Example" }, "emailVerified": { "type": "boolean", "description": "True once the address passed a help center auth flow.", "example": true }, "disabled": { "type": "boolean", "description": "Disabled users keep no active sessions.", "example": false }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "number" }, { "type": "boolean" } ] }, { "maxItems": 64, "type": "array", "items": { "type": "string", "maxLength": 256 } }, { "maxItems": 64, "type": "array", "items": { "type": "number" } }, { "maxItems": 64, "type": "array", "items": { "type": "boolean" } } ] }, "description": "Saved attributes that user-group audience rules match on, with nested objects flattened into dot-path keys.", "example": { "plan": "enterprise", "role": "admin", "beta": true, "seats": 25, "groups": [ "beta", "internal" ], "availableFrameworks.csrd": true } }, "lastLoginAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "Most recent help center sign-in.", "example": "2026-01-15T18:25:43.511Z" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "helpdeskId", "email", "name", "emailVerified", "disabled", "attributes", "lastLoginAt", "createdAt", "updatedAt" ], "description": "A help center end user." }, "description": "Items on this page." }, "has_more": { "type": "boolean", "description": "True when further pages follow.", "example": true }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `start_cursor` for the next page; null on the last page.", "example": "eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ" } }, "required": [ "results", "has_more", "next_cursor" ], "description": "One page of results plus the cursor to the next." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope, or your plan does not include help center user management", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "query", "name": "start_cursor", "schema": { "example": "eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ", "type": "string" }, "description": "Opaque cursor taken from the previous response’s `next_cursor`." }, { "in": "query", "name": "page_size", "schema": { "default": 20, "example": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Items per page." }, { "in": "query", "name": "email", "schema": { "example": "alice@example.com", "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "description": "Exact address to look up, matched case-insensitively." } ] }, "post": { "operationId": "createHelpCenterUser", "tags": [ "Users" ], "summary": "Create a help center user", "description": "Creates a help center user, whose saved attributes are what user-group audience rules match on.\n\n**Required scope:** `content:write`", "responses": { "201": { "description": "Created help center user", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Help center user identifier.", "example": "hcusr_01JXYB3S2Y8C" }, "helpdeskId": { "type": "string", "description": "Help center identifier.", "example": "help_01JXYA7B3T7G" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Email address, stored lowercase.", "example": "alice@example.com" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name.", "example": "Alice Example" }, "emailVerified": { "type": "boolean", "description": "True once the address passed a help center auth flow.", "example": true }, "disabled": { "type": "boolean", "description": "Disabled users keep no active sessions.", "example": false }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "number" }, { "type": "boolean" } ] }, { "maxItems": 64, "type": "array", "items": { "type": "string", "maxLength": 256 } }, { "maxItems": 64, "type": "array", "items": { "type": "number" } }, { "maxItems": 64, "type": "array", "items": { "type": "boolean" } } ] }, "description": "Saved attributes that user-group audience rules match on, with nested objects flattened into dot-path keys.", "example": { "plan": "enterprise", "role": "admin", "beta": true, "seats": 25, "groups": [ "beta", "internal" ], "availableFrameworks.csrd": true } }, "lastLoginAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "Most recent help center sign-in.", "example": "2026-01-15T18:25:43.511Z" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "helpdeskId", "email", "name", "emailVerified", "disabled", "attributes", "lastLoginAt", "createdAt", "updatedAt" ], "description": "A help center end user." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Your plan does not include help center user management", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "409": { "description": "A help center user already exists with this email", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Email address, stored lowercase.", "example": "alice@example.com" }, "name": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "Display name.", "example": "Alice Example" }, "attributes": { "description": "Attributes to save for user-group matching.", "example": { "plan": "enterprise" }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "number" }, { "type": "boolean" } ] }, { "maxItems": 64, "type": "array", "items": { "type": "string", "maxLength": 256 } }, { "maxItems": 64, "type": "array", "items": { "type": "number" } }, { "maxItems": 64, "type": "array", "items": { "type": "boolean" } } ] }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "number" }, { "type": "boolean" } ] }, { "maxItems": 64, "type": "array", "items": { "type": "string", "maxLength": 256 } }, { "maxItems": 64, "type": "array", "items": { "type": "number" } }, { "maxItems": 64, "type": "array", "items": { "type": "boolean" } } ] }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "number" }, { "type": "boolean" } ] }, { "maxItems": 64, "type": "array", "items": { "type": "string", "maxLength": 256 } }, { "maxItems": 64, "type": "array", "items": { "type": "number" } }, { "maxItems": 64, "type": "array", "items": { "type": "boolean" } } ] }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "number" }, { "type": "boolean" } ] }, { "maxItems": 64, "type": "array", "items": { "type": "string", "maxLength": 256 } }, { "maxItems": 64, "type": "array", "items": { "type": "number" } }, { "maxItems": 64, "type": "array", "items": { "type": "boolean" } } ] } } ] } } ] } } ] } }, "disabled": { "default": false, "description": "Creates the user unable to hold a session.", "example": false, "type": "boolean" } }, "required": [ "email" ], "description": "New help center user." } } } } } }, "/users/{id}": { "get": { "operationId": "getHelpCenterUser", "tags": [ "Users" ], "summary": "Get a help center user", "description": "Returns one help center user with their saved attributes.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Help center user", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Help center user identifier.", "example": "hcusr_01JXYB3S2Y8C" }, "helpdeskId": { "type": "string", "description": "Help center identifier.", "example": "help_01JXYA7B3T7G" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Email address, stored lowercase.", "example": "alice@example.com" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name.", "example": "Alice Example" }, "emailVerified": { "type": "boolean", "description": "True once the address passed a help center auth flow.", "example": true }, "disabled": { "type": "boolean", "description": "Disabled users keep no active sessions.", "example": false }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "number" }, { "type": "boolean" } ] }, { "maxItems": 64, "type": "array", "items": { "type": "string", "maxLength": 256 } }, { "maxItems": 64, "type": "array", "items": { "type": "number" } }, { "maxItems": 64, "type": "array", "items": { "type": "boolean" } } ] }, "description": "Saved attributes that user-group audience rules match on, with nested objects flattened into dot-path keys.", "example": { "plan": "enterprise", "role": "admin", "beta": true, "seats": 25, "groups": [ "beta", "internal" ], "availableFrameworks.csrd": true } }, "lastLoginAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "Most recent help center sign-in.", "example": "2026-01-15T18:25:43.511Z" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "helpdeskId", "email", "name", "emailVerified", "disabled", "attributes", "lastLoginAt", "createdAt", "updatedAt" ], "description": "A help center end user." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Your plan does not include help center user management", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "404": { "description": "Help center user not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "hcusr_01JXYB3S2Y8C" }, "required": true, "description": "Help center user identifier." } ] }, "patch": { "operationId": "updateHelpCenterUser", "tags": [ "Users" ], "summary": "Update a help center user", "description": "Updates a help center user. Attributes are replaced wholesale, never merged.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Updated help center user", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Help center user identifier.", "example": "hcusr_01JXYB3S2Y8C" }, "helpdeskId": { "type": "string", "description": "Help center identifier.", "example": "help_01JXYA7B3T7G" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Email address, stored lowercase.", "example": "alice@example.com" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name.", "example": "Alice Example" }, "emailVerified": { "type": "boolean", "description": "True once the address passed a help center auth flow.", "example": true }, "disabled": { "type": "boolean", "description": "Disabled users keep no active sessions.", "example": false }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "number" }, { "type": "boolean" } ] }, { "maxItems": 64, "type": "array", "items": { "type": "string", "maxLength": 256 } }, { "maxItems": 64, "type": "array", "items": { "type": "number" } }, { "maxItems": 64, "type": "array", "items": { "type": "boolean" } } ] }, "description": "Saved attributes that user-group audience rules match on, with nested objects flattened into dot-path keys.", "example": { "plan": "enterprise", "role": "admin", "beta": true, "seats": 25, "groups": [ "beta", "internal" ], "availableFrameworks.csrd": true } }, "lastLoginAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "Most recent help center sign-in.", "example": "2026-01-15T18:25:43.511Z" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "helpdeskId", "email", "name", "emailVerified", "disabled", "attributes", "lastLoginAt", "createdAt", "updatedAt" ], "description": "A help center end user." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Your plan does not include help center user management", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "404": { "description": "Help center user not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "409": { "description": "Another help center user already exists with this email", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "hcusr_01JXYB3S2Y8C" }, "required": true, "description": "Help center user identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Email address, stored lowercase.", "example": "alice@example.com" }, "name": { "description": "New display name, or null to clear it.", "example": "Alice Example", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "attributes": { "description": "Replaces the whole saved attributes object; omit to leave it untouched.", "example": { "plan": "enterprise" }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "number" }, { "type": "boolean" } ] }, { "maxItems": 64, "type": "array", "items": { "type": "string", "maxLength": 256 } }, { "maxItems": 64, "type": "array", "items": { "type": "number" } }, { "maxItems": 64, "type": "array", "items": { "type": "boolean" } } ] }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "number" }, { "type": "boolean" } ] }, { "maxItems": 64, "type": "array", "items": { "type": "string", "maxLength": 256 } }, { "maxItems": 64, "type": "array", "items": { "type": "number" } }, { "maxItems": 64, "type": "array", "items": { "type": "boolean" } } ] }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "number" }, { "type": "boolean" } ] }, { "maxItems": 64, "type": "array", "items": { "type": "string", "maxLength": 256 } }, { "maxItems": 64, "type": "array", "items": { "type": "number" } }, { "maxItems": 64, "type": "array", "items": { "type": "boolean" } } ] }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "number" }, { "type": "boolean" } ] }, { "maxItems": 64, "type": "array", "items": { "type": "string", "maxLength": 256 } }, { "maxItems": 64, "type": "array", "items": { "type": "number" } }, { "maxItems": 64, "type": "array", "items": { "type": "boolean" } } ] } } ] } } ] } } ] } }, "disabled": { "description": "Disabling drops the user’s active sessions.", "example": false, "type": "boolean" } }, "description": "Help center user changes." } } } } } }, "/tasks": { "get": { "operationId": "listTasks", "tags": [ "Tasks" ], "summary": "List tasks", "description": "Returns your AI tasks, newest first.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Cursor-paginated tasks", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Task identifier.", "example": "tsk_01JXYAQ4M7RC" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Task title, generated by Fern when none was supplied.", "example": "Create API key onboarding docs" }, "status": { "type": "string", "description": "Processing status.", "example": "in_progress" } }, "required": [ "id", "title", "status" ], "description": "An AI task." }, "description": "Items on this page." }, "has_more": { "type": "boolean", "description": "True when further pages follow.", "example": true }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `start_cursor` for the next page; null on the last page.", "example": "eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ" } }, "required": [ "results", "has_more", "next_cursor" ], "description": "One page of results plus the cursor to the next." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "query", "name": "start_cursor", "schema": { "example": "eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ", "type": "string" }, "description": "Opaque cursor taken from the previous response’s `next_cursor`." }, { "in": "query", "name": "page_size", "schema": { "default": 20, "example": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Items per page." }, { "in": "query", "name": "status", "schema": { "example": "completed", "type": "string" }, "description": "Restricts the list to one processing status." } ] }, "post": { "operationId": "createTask", "tags": [ "Tasks" ], "summary": "Create a task", "description": "Creates a task and queues it for Fern. Processing is asynchronous, so poll the task to see what it produced.\n\n**Required scope:** `content:write`", "responses": { "201": { "description": "Created task", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Task identifier.", "example": "tsk_01JXYAQ4M7RC" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Task title, generated by Fern when none was supplied.", "example": "Create API key onboarding docs" }, "status": { "type": "string", "description": "Processing status.", "example": "in_progress" } }, "required": [ "id", "title", "status" ], "description": "An AI task." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "429": { "description": "Rate limit exceeded (10 requests per hour per API key). Retry after the number of seconds in the `Retry-After` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Rate limit exceeded" }, "code": { "type": "string", "const": "rate_limited" } }, "required": [ "error", "code" ], "description": "Returned when a request exceeds the global or a per-operation rate limit; a `Retry-After` header carries the seconds to wait." } } } }, "500": { "description": "Task could not be queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "description": "What Fern should generate or update.", "example": "Create a quickstart article for API key authentication." }, "title": { "description": "Task title; Fern generates one when it is left out.", "example": "Create API key onboarding docs", "type": "string", "minLength": 1 } }, "required": [ "description" ], "description": "New AI task." } } } } } }, "/tasks/{id}": { "get": { "operationId": "getTask", "tags": [ "Tasks" ], "summary": "Get a task", "description": "Returns a task with the content changes it proposed or applied.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Task with outputs", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Task identifier.", "example": "tsk_01JXYAQ4M7RC" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Task title, generated by Fern when none was supplied.", "example": "Create API key onboarding docs" }, "status": { "type": "string", "description": "Processing status.", "example": "in_progress" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Output identifier.", "example": "tout_01JXYAQ4M7RC" }, "kind": { "type": "string", "description": "Content type this output targets.", "example": "article" }, "operation": { "type": "string", "description": "Change Fern proposed.", "example": "create" }, "status": { "type": "string", "description": "Whether the change was applied.", "example": "applied" }, "title": { "type": "string", "description": "Title of the produced content.", "example": "Getting started with API keys" }, "targetArticleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Article this output wrote to.", "example": "art_01JXY9AZK4KV" }, "targetCollectionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Collection this output wrote to.", "example": "col_01JXYA6ABN52" }, "targetSectionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Section this output wrote to.", "example": "sect_01JXYA4T1JNT" }, "appliedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ] } }, "required": [ "id", "kind", "operation", "status", "title", "targetArticleId", "targetCollectionId", "targetSectionId", "appliedAt" ], "description": "One content change a task proposed or applied." }, "description": "Content changes this task produced." } }, "required": [ "id", "title", "status", "outputs" ], "description": "A task and the content it produced." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." } ] } }, "/analytics/overview": { "get": { "operationId": "getOverviewAnalytics", "tags": [ "Analytics" ], "summary": "Get overview analytics", "description": "Visitor, view, and search KPIs, with daily history.\n\n**Required scope:** `analytics:read`", "responses": { "200": { "description": "Metrics for the requested date range", "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Analytics metrics, which read as zero rather than erroring during an analytics pipeline outage." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "analytics:read" ], "parameters": [ { "in": "query", "name": "start_date", "schema": { "example": "2026-01-01", "type": "string" }, "description": "Earliest date to include." }, { "in": "query", "name": "end_date", "schema": { "example": "2026-01-31", "type": "string" }, "description": "Latest date to include." } ] } }, "/analytics/articles": { "get": { "operationId": "getArticleAnalytics", "tags": [ "Analytics" ], "summary": "Get per-article analytics", "description": "View, unique-viewer, search-select, and feedback counts for each published article.\n\n**Required scope:** `analytics:read`", "responses": { "200": { "description": "Metrics for the requested date range", "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Analytics metrics, which read as zero rather than erroring during an analytics pipeline outage." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "analytics:read" ], "parameters": [ { "in": "query", "name": "start_date", "schema": { "example": "2026-01-01", "type": "string" }, "description": "Earliest date to include." }, { "in": "query", "name": "end_date", "schema": { "example": "2026-01-31", "type": "string" }, "description": "Latest date to include." }, { "in": "query", "name": "limit", "schema": { "example": 50, "type": "integer", "minimum": 1, "maximum": 500 }, "description": "Maximum rows to return." } ] } }, "/analytics/searches": { "get": { "operationId": "getSearchAnalytics", "tags": [ "Analytics" ], "summary": "Get search analytics", "description": "Top search terms and missed terms — searches that returned no results — with their outcomes.\n\n**Required scope:** `analytics:read`", "responses": { "200": { "description": "Metrics for the requested date range", "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Analytics metrics, which read as zero rather than erroring during an analytics pipeline outage." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "analytics:read" ], "parameters": [ { "in": "query", "name": "start_date", "schema": { "example": "2026-01-01", "type": "string" }, "description": "Earliest date to include." }, { "in": "query", "name": "end_date", "schema": { "example": "2026-01-31", "type": "string" }, "description": "Latest date to include." }, { "in": "query", "name": "limit", "schema": { "example": 50, "type": "integer", "minimum": 1, "maximum": 500 }, "description": "Maximum rows to return." } ] } }, "/analytics/feedback": { "get": { "operationId": "getFeedbackAnalytics", "tags": [ "Analytics" ], "summary": "Get feedback analytics", "description": "Helpfulness KPIs and a rollup of recent feedback. Use `/feedback` for a paginated, triageable list.\n\n**Required scope:** `analytics:read`", "responses": { "200": { "description": "Metrics for the requested date range", "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Analytics metrics, which read as zero rather than erroring during an analytics pipeline outage." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "analytics:read" ], "parameters": [ { "in": "query", "name": "start_date", "schema": { "example": "2026-01-01", "type": "string" }, "description": "Earliest date to include." }, { "in": "query", "name": "end_date", "schema": { "example": "2026-01-31", "type": "string" }, "description": "Latest date to include." } ] } }, "/feedback": { "post": { "operationId": "createArticleFeedback", "tags": [ "Feedback" ], "summary": "Create article feedback", "description": "Records a reader’s helpful-or-not verdict on an article, the same signal the help center collects.\n\n**Required scope:** `content:write`", "responses": { "201": { "description": "Created feedback", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Feedback identifier.", "example": "artfb_01JXY9AZK4KV" }, "articleId": { "anyOf": [ { "type": "string", "description": "Article identifier.", "example": "art_01JXY9AZK4KV" }, { "type": "null" } ] }, "articleTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Article title at submission time.", "example": "Getting started with API keys" }, "type": { "type": "string", "enum": [ "positive", "negative" ], "description": "Whether the reader found the article helpful.", "example": "positive" }, "feedback": { "type": "string", "description": "Reader’s free text; treat as untrusted.", "example": "This walkthrough was clear and accurate." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Address the reader supplied, or null when anonymous.", "example": "alice@example.com" }, "resolved": { "type": "boolean", "description": "Triage state.", "example": false }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "user": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Help center user identifier.", "example": "hcusr_01JXYB3S2Y8C" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name.", "example": "Alice Example" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Email address, stored lowercase.", "example": "alice@example.com" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ], "description": "Help center user matched from the submitter’s email, or null when anonymous or unrecognized." } }, "required": [ "id", "articleId", "articleTitle", "type", "feedback", "email", "resolved", "createdAt", "user" ], "description": "One piece of reader feedback on an article." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Article not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "429": { "description": "Rate limit exceeded (300 requests per hour per API key). Retry after the number of seconds in the `Retry-After` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Rate limit exceeded" }, "code": { "type": "string", "const": "rate_limited" } }, "required": [ "error", "code" ], "description": "Returned when a request exceeds the global or a per-operation rate limit; a `Retry-After` header carries the seconds to wait." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "article_id": { "type": "string", "description": "Article identifier.", "example": "art_01JXY9AZK4KV" }, "type": { "type": "string", "enum": [ "positive", "negative" ], "description": "Whether the reader found the article helpful.", "example": "positive" }, "feedback": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "Reader’s free text; treat as untrusted.", "example": "This walkthrough was clear and accurate." }, "email": { "description": "Submitter address; a match links the feedback to that help center user.", "example": "alice@example.com", "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "article_id", "type", "feedback" ], "description": "New article feedback." } } } } }, "get": { "operationId": "listArticleFeedback", "tags": [ "Feedback" ], "summary": "List article feedback", "description": "Returns article feedback, newest first.\n\n**Required scope:** `analytics:read`", "responses": { "200": { "description": "Feedback page", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Feedback identifier.", "example": "artfb_01JXY9AZK4KV" }, "articleId": { "anyOf": [ { "type": "string", "description": "Article identifier.", "example": "art_01JXY9AZK4KV" }, { "type": "null" } ] }, "articleTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Article title at submission time.", "example": "Getting started with API keys" }, "type": { "type": "string", "enum": [ "positive", "negative" ], "description": "Whether the reader found the article helpful.", "example": "positive" }, "feedback": { "type": "string", "description": "Reader’s free text; treat as untrusted.", "example": "This walkthrough was clear and accurate." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Address the reader supplied, or null when anonymous.", "example": "alice@example.com" }, "resolved": { "type": "boolean", "description": "Triage state.", "example": false }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "user": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Help center user identifier.", "example": "hcusr_01JXYB3S2Y8C" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name.", "example": "Alice Example" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Email address, stored lowercase.", "example": "alice@example.com" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ], "description": "Help center user matched from the submitter’s email, or null when anonymous or unrecognized." } }, "required": [ "id", "articleId", "articleTitle", "type", "feedback", "email", "resolved", "createdAt", "user" ], "description": "One piece of reader feedback on an article." }, "description": "Items on this page." }, "has_more": { "type": "boolean", "description": "True when further pages follow.", "example": true }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `start_cursor` for the next page; null on the last page.", "example": "eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ" } }, "required": [ "results", "has_more", "next_cursor" ], "description": "One page of results plus the cursor to the next." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "analytics:read" ], "parameters": [ { "in": "query", "name": "start_cursor", "schema": { "example": "eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ", "type": "string" }, "description": "Opaque cursor taken from the previous response’s `next_cursor`." }, { "in": "query", "name": "page_size", "schema": { "default": 20, "example": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Items per page." }, { "in": "query", "name": "article_id", "schema": { "example": "art_01JXY9AZK4KV", "type": "string" }, "description": "Restricts the list to one article." }, { "in": "query", "name": "type", "schema": { "example": "negative", "type": "string", "enum": [ "positive", "negative" ] }, "description": "Restricts the list to one verdict." }, { "in": "query", "name": "resolved", "schema": { "example": "false", "type": "string", "enum": [ "true", "false" ] }, "description": "Restricts the list to one triage state." } ] } }, "/feedback/{id}": { "get": { "operationId": "getArticleFeedback", "tags": [ "Feedback" ], "summary": "Get feedback", "description": "Returns one feedback entry.\n\n**Required scope:** `analytics:read`", "responses": { "200": { "description": "Feedback", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Feedback identifier.", "example": "artfb_01JXY9AZK4KV" }, "articleId": { "anyOf": [ { "type": "string", "description": "Article identifier.", "example": "art_01JXY9AZK4KV" }, { "type": "null" } ] }, "articleTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Article title at submission time.", "example": "Getting started with API keys" }, "type": { "type": "string", "enum": [ "positive", "negative" ], "description": "Whether the reader found the article helpful.", "example": "positive" }, "feedback": { "type": "string", "description": "Reader’s free text; treat as untrusted.", "example": "This walkthrough was clear and accurate." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Address the reader supplied, or null when anonymous.", "example": "alice@example.com" }, "resolved": { "type": "boolean", "description": "Triage state.", "example": false }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "user": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Help center user identifier.", "example": "hcusr_01JXYB3S2Y8C" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name.", "example": "Alice Example" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Email address, stored lowercase.", "example": "alice@example.com" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ], "description": "Help center user matched from the submitter’s email, or null when anonymous or unrecognized." } }, "required": [ "id", "articleId", "articleTitle", "type", "feedback", "email", "resolved", "createdAt", "user" ], "description": "One piece of reader feedback on an article." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Feedback not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "analytics:read" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] }, "patch": { "operationId": "updateArticleFeedback", "tags": [ "Feedback" ], "summary": "Update feedback triage", "description": "Marks a feedback entry as resolved or unresolved.\n\n**Required scope:** `content:write`", "responses": { "200": { "description": "Updated triage state", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Feedback identifier.", "example": "artfb_01JXY9AZK4KV" }, "resolved": { "type": "boolean", "description": "Triage state after the update.", "example": true } }, "required": [ "id", "resolved" ], "description": "Feedback triage state after the update." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Feedback not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "content:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resolved": { "type": "boolean", "description": "New triage state.", "example": true } }, "required": [ "resolved" ], "description": "Feedback triage change." } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } }, "/assistant/conversations": { "get": { "operationId": "listAssistantConversations", "tags": [ "Assistant conversations" ], "summary": "List assistant conversations", "description": "Returns AI assistant conversations, newest first.\n\n**Required scope:** `conversations:read`", "responses": { "200": { "description": "Cursor-paginated conversations. With a `feedback` or `coverage` filter the scan is bounded to 10 windows per request, so a page may come back short with `has_more` true; follow `next_cursor` to continue the scan without skipping matches", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Conversation identifier.", "example": "conv_01JXY9AZK4KV" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "status": { "type": "string", "description": "Conversation lifecycle status.", "example": "active" }, "source": { "anyOf": [ { "type": "string", "enum": [ "help", "widget" ] }, { "type": "null" } ], "description": "Surface the conversation started on.", "example": "widget" }, "pageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Page the visitor was on when the conversation started, when captured.", "example": "https://example.com/pricing" }, "user": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Help center user identifier.", "example": "hcusr_01JXYB3S2Y8C" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name.", "example": "Alice Example" } }, "required": [ "id", "name" ] }, { "type": "null" } ], "description": "Help center user behind the conversation, or null when the visitor was anonymous." }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "One-line AI summary of the conversation.", "example": "Asked how to rotate an API key." }, "coverage": { "anyOf": [ { "type": "string", "enum": [ "covered", "partial", "none", "irrelevant" ] }, { "type": "null" } ], "description": "How well existing content answered the question.", "example": "covered" }, "feedback": { "anyOf": [ { "type": "string", "enum": [ "positive", "negative" ] }, { "type": "null" } ], "description": "Thumbs rating the visitor left, or null when they left none.", "example": "positive" }, "escalated": { "type": "boolean", "description": "True when the conversation was handed to a human.", "example": false }, "messageCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Visitor messages in the conversation.", "example": 4 } }, "required": [ "id", "createdAt", "updatedAt", "status", "source", "pageUrl", "user", "summary", "coverage", "feedback", "escalated", "messageCount" ], "description": "An AI assistant conversation, without its transcript." }, "description": "Items on this page." }, "has_more": { "type": "boolean", "description": "True when further pages follow.", "example": true }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `start_cursor` for the next page; null on the last page.", "example": "eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ" } }, "required": [ "results", "has_more", "next_cursor" ], "description": "One page of results plus the cursor to the next." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "conversations:read" ], "parameters": [ { "in": "query", "name": "start_cursor", "schema": { "example": "eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ", "type": "string" }, "description": "Opaque cursor taken from the previous response’s `next_cursor`." }, { "in": "query", "name": "page_size", "schema": { "default": 20, "example": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Items per page." }, { "in": "query", "name": "feedback", "schema": { "example": "negative", "type": "string", "enum": [ "all", "positive", "negative", "none" ] }, "description": "Restricts the list to one thumbs rating." }, { "in": "query", "name": "coverage", "schema": { "example": "none", "type": "string", "enum": [ "all", "covered", "partial", "none", "irrelevant" ] }, "description": "Restricts the list to one coverage verdict." }, { "in": "query", "name": "start_date", "schema": { "example": "2026-01-01", "type": "string" }, "description": "Earliest date to include." }, { "in": "query", "name": "end_date", "schema": { "example": "2026-01-31", "type": "string" }, "description": "Latest date to include." } ] } }, "/assistant/conversations/{id}": { "get": { "operationId": "getConversationTranscript", "tags": [ "Assistant conversations" ], "summary": "Get a conversation transcript", "description": "Returns a conversation with its transcript, sanitized of tool calls, reasoning, and internal metadata.\n\n**Required scope:** `conversations:read`", "responses": { "200": { "description": "Conversation transcript", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Conversation identifier.", "example": "conv_01JXY9AZK4KV" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "status": { "type": "string", "description": "Conversation lifecycle status.", "example": "active" }, "source": { "anyOf": [ { "type": "string", "enum": [ "help", "widget" ] }, { "type": "null" } ], "description": "Surface the conversation started on.", "example": "widget" }, "pageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Page the visitor was on when the conversation started, when captured.", "example": "https://example.com/pricing" }, "user": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Help center user identifier.", "example": "hcusr_01JXYB3S2Y8C" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name.", "example": "Alice Example" } }, "required": [ "id", "name" ] }, { "type": "null" } ], "description": "Help center user behind the conversation, or null when the visitor was anonymous." }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "One-line AI summary of the conversation.", "example": "Asked how to rotate an API key." }, "coverage": { "anyOf": [ { "type": "string", "enum": [ "covered", "partial", "none", "irrelevant" ] }, { "type": "null" } ], "description": "How well existing content answered the question.", "example": "covered" }, "feedback": { "anyOf": [ { "type": "string", "enum": [ "positive", "negative" ] }, { "type": "null" } ], "description": "Thumbs rating the visitor left, or null when they left none.", "example": "positive" }, "escalated": { "type": "boolean", "description": "True when the conversation was handed to a human.", "example": false }, "messageCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Visitor messages in the conversation.", "example": 4 }, "transcript": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ], "description": "Who spoke.", "example": "assistant" }, "text": { "type": "string", "description": "Plain-text message, stripped of metadata fences.", "example": "You can rotate a key from Developer settings." } }, "required": [ "role", "text" ], "description": "One turn of a transcript." }, "description": "Visitor and assistant turns only; tool calls and reasoning are excluded." }, "references": { "type": "array", "items": { "type": "object", "properties": { "articleId": { "type": "string", "description": "Article identifier.", "example": "art_01JXY9AZK4KV" }, "title": { "type": "string", "description": "Article title as cited, falling back to the current title.", "example": "Getting started with API keys" } }, "required": [ "articleId", "title" ], "description": "An article the assistant cited." }, "description": "Articles the assistant cited across the conversation." } }, "required": [ "id", "createdAt", "updatedAt", "status", "source", "pageUrl", "user", "summary", "coverage", "feedback", "escalated", "messageCount", "transcript", "references" ], "description": "A conversation and its sanitized transcript." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "conversations:read" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "art_01JXY9AZK4KV" }, "required": true, "description": "Identifier of the requested resource." } ] } }, "/webhooks": { "post": { "operationId": "createWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Create a webhook endpoint", "description": "Registers an HTTPS endpoint to receive event deliveries. The signing secret is returned here once and never again.\n\n**Required scope:** `webhooks:manage`", "responses": { "200": { "description": "Created endpoint, including its signing secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook endpoint identifier.", "example": "whep_01JXY9AZK4KV" }, "url": { "type": "string", "description": "Destination that receives POSTed deliveries.", "example": "https://example.com/hooks/ferndesk" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed event types, or `*`.", "example": [ "article.published" ] }, "enabled": { "type": "boolean", "description": "Endpoints auto-disable after sustained failures.", "example": true }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Label shown in the dashboard.", "example": "Prod sync worker" }, "failureCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Consecutive failures, reset by any success or a re-enable.", "example": 0 }, "lastSuccessAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ] }, "lastFailureAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ] }, "disabledAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "When sustained failures disabled the endpoint.", "example": "2026-01-15T18:25:43.511Z" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "secret": { "type": "string", "description": "Key for verifying `webhook-signature`, shown only in this response.", "example": "whsec_Zm9vYmFyYmF6cXV4" } }, "required": [ "id", "url", "events", "enabled", "description", "failureCount", "lastSuccessAt", "lastFailureAt", "disabledAt", "createdAt", "updatedAt", "secret" ], "description": "A new endpoint, with the one-time signing secret." } } } }, "400": { "description": "Invalid URL or event types", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:manage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "Destination URL; `http://` is accepted only for localhost.", "example": "https://example.com/hooks/ferndesk" }, "events": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "Event types to subscribe to, or `*` for every event.", "example": [ "article.published", "article.updated" ] }, "description": { "description": "Label shown in the dashboard.", "example": "Prod sync worker", "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "url", "events" ], "description": "New webhook endpoint." } } } } }, "get": { "operationId": "listWebhookEndpoints", "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "description": "Returns every webhook endpoint for your organization, newest first.\n\n**Required scope:** `webhooks:manage`", "responses": { "200": { "description": "Webhook endpoints", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook endpoint identifier.", "example": "whep_01JXY9AZK4KV" }, "url": { "type": "string", "description": "Destination that receives POSTed deliveries.", "example": "https://example.com/hooks/ferndesk" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed event types, or `*`.", "example": [ "article.published" ] }, "enabled": { "type": "boolean", "description": "Endpoints auto-disable after sustained failures.", "example": true }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Label shown in the dashboard.", "example": "Prod sync worker" }, "failureCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Consecutive failures, reset by any success or a re-enable.", "example": 0 }, "lastSuccessAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ] }, "lastFailureAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ] }, "disabledAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "When sustained failures disabled the endpoint.", "example": "2026-01-15T18:25:43.511Z" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "url", "events", "enabled", "description", "failureCount", "lastSuccessAt", "lastFailureAt", "disabledAt", "createdAt", "updatedAt" ], "description": "A registered webhook endpoint, never including its signing secret." } } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:manage" ] } }, "/webhooks/{id}": { "get": { "operationId": "getWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Get a webhook endpoint", "description": "Returns one endpoint together with its recent deliveries.\n\n**Required scope:** `webhooks:manage`", "responses": { "200": { "description": "Endpoint with recent deliveries", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook endpoint identifier.", "example": "whep_01JXY9AZK4KV" }, "url": { "type": "string", "description": "Destination that receives POSTed deliveries.", "example": "https://example.com/hooks/ferndesk" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed event types, or `*`.", "example": [ "article.published" ] }, "enabled": { "type": "boolean", "description": "Endpoints auto-disable after sustained failures.", "example": true }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Label shown in the dashboard.", "example": "Prod sync worker" }, "failureCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Consecutive failures, reset by any success or a re-enable.", "example": 0 }, "lastSuccessAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ] }, "lastFailureAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ] }, "disabledAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "When sustained failures disabled the endpoint.", "example": "2026-01-15T18:25:43.511Z" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Delivery identifier.", "example": "whdl_01JXY9AZK4KV" }, "eventType": { "type": "string", "description": "Event type delivered.", "example": "article.published" }, "status": { "type": "string", "enum": [ "pending", "success", "failed" ], "description": "Delivery lifecycle status.", "example": "success" }, "responseStatus": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Status your endpoint returned, or null before any response arrived.", "example": 200 }, "attempts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Attempts made so far.", "example": 1 }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error from the most recent failed attempt.", "example": "connect ETIMEDOUT" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "deliveredAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "When the delivery first succeeded.", "example": "2026-01-15T18:25:43.511Z" }, "nextRetryAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "When the next retry is scheduled.", "example": "2026-01-15T18:30:43.511Z" } }, "required": [ "id", "eventType", "status", "responseStatus", "attempts", "error", "createdAt", "deliveredAt", "nextRetryAt" ], "description": "One attempt to deliver an event to an endpoint." }, "description": "Up to 20 most recent deliveries, newest first." } }, "required": [ "id", "url", "events", "enabled", "description", "failureCount", "lastSuccessAt", "lastFailureAt", "disabledAt", "createdAt", "updatedAt", "deliveries" ], "description": "An endpoint with its recent deliveries." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Endpoint not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:manage" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "whep_01JXY9AZK4KV" }, "required": true, "description": "Webhook endpoint identifier." } ] }, "patch": { "operationId": "updateWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Update a webhook endpoint", "description": "Updates a webhook endpoint. Re-enabling a disabled endpoint also resets its failure counter.\n\n**Required scope:** `webhooks:manage`", "responses": { "200": { "description": "Updated endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook endpoint identifier.", "example": "whep_01JXY9AZK4KV" }, "url": { "type": "string", "description": "Destination that receives POSTed deliveries.", "example": "https://example.com/hooks/ferndesk" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed event types, or `*`.", "example": [ "article.published" ] }, "enabled": { "type": "boolean", "description": "Endpoints auto-disable after sustained failures.", "example": true }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Label shown in the dashboard.", "example": "Prod sync worker" }, "failureCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Consecutive failures, reset by any success or a re-enable.", "example": 0 }, "lastSuccessAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ] }, "lastFailureAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ] }, "disabledAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "When sustained failures disabled the endpoint.", "example": "2026-01-15T18:25:43.511Z" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" } }, "required": [ "id", "url", "events", "enabled", "description", "failureCount", "lastSuccessAt", "lastFailureAt", "disabledAt", "createdAt", "updatedAt" ], "description": "A registered webhook endpoint, never including its signing secret." } } } }, "400": { "description": "Invalid URL or event types", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Endpoint not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:manage" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "whep_01JXY9AZK4KV" }, "required": true, "description": "Webhook endpoint identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "New destination URL.", "example": "https://example.com/hooks/ferndesk", "type": "string", "minLength": 1, "maxLength": 2048 }, "events": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "Event types to subscribe to, or `*` for every event.", "example": [ "article.published", "article.updated" ] }, "description": { "description": "New label.", "example": "Prod sync worker", "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "enabled": { "description": "Re-enabling also clears the failure counter and auto-disable state.", "example": true, "type": "boolean" } }, "description": "Webhook endpoint changes." } } } } }, "delete": { "operationId": "deleteWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Delete a webhook endpoint", "description": "Permanently deletes an endpoint and its delivery history.\n\n**Required scope:** `webhooks:manage`", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the deleted resource.", "example": "col_01JXYA6ABN52" }, "deleted": { "type": "boolean", "const": true, "description": "Always true on a successful delete.", "example": true } }, "required": [ "id", "deleted" ] } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Endpoint not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:manage" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "whep_01JXY9AZK4KV" }, "required": true, "description": "Webhook endpoint identifier." } ] } }, "/webhooks/{id}/test": { "post": { "operationId": "sendWebhookTestDelivery", "tags": [ "Webhooks" ], "summary": "Send a test delivery", "description": "Sends a `webhook.test` event through the real delivery pipeline, signed exactly like a production event.\n\n**Required scope:** `webhooks:manage`", "responses": { "200": { "description": "Test delivery queued. Delivery is asynchronous — poll the delivery endpoint with the returned `delivery_id` for the outcome", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery_id": { "type": "string", "description": "Queued delivery to poll for the outcome.", "example": "whdl_01JXY9AZK4KV" } }, "required": [ "delivery_id" ], "description": "The queued test delivery." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Endpoint not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "429": { "description": "Rate limit exceeded (5 requests per minute per API key). Retry after the number of seconds in the `Retry-After` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Rate limit exceeded" }, "code": { "type": "string", "const": "rate_limited" } }, "required": [ "error", "code" ], "description": "Returned when a request exceeds the global or a per-operation rate limit; a `Retry-After` header carries the seconds to wait." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:manage" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "whep_01JXY9AZK4KV" }, "required": true, "description": "Webhook endpoint identifier." } ] } }, "/webhooks/{id}/deliveries/{deliveryId}": { "get": { "operationId": "getWebhookDelivery", "tags": [ "Webhooks" ], "summary": "Get a delivery", "description": "Returns one delivery record, including its attempt history and retry state.\n\n**Required scope:** `webhooks:manage`", "responses": { "200": { "description": "Delivery record", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Delivery identifier.", "example": "whdl_01JXY9AZK4KV" }, "eventType": { "type": "string", "description": "Event type delivered.", "example": "article.published" }, "status": { "type": "string", "enum": [ "pending", "success", "failed" ], "description": "Delivery lifecycle status.", "example": "success" }, "responseStatus": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Status your endpoint returned, or null before any response arrived.", "example": 200 }, "attempts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Attempts made so far.", "example": 1 }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error from the most recent failed attempt.", "example": "connect ETIMEDOUT" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, "deliveredAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "When the delivery first succeeded.", "example": "2026-01-15T18:25:43.511Z" }, "nextRetryAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp in UTC.", "example": "2026-01-15T18:25:43.511Z" }, { "type": "null" } ], "description": "When the next retry is scheduled.", "example": "2026-01-15T18:30:43.511Z" } }, "required": [ "id", "eventType", "status", "responseStatus", "attempts", "error", "createdAt", "deliveredAt", "nextRetryAt" ], "description": "One attempt to deliver an event to an endpoint." } } } }, "401": { "description": "Unauthorized: missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This endpoint requires the `content:write` scope." }, "code": { "type": "string", "const": "missing_scope" }, "scope": { "type": "string", "example": "content:write" } }, "required": [ "error", "code", "scope" ], "description": "Returned when the API key lacks the scope an endpoint requires." } } } }, "404": { "description": "Delivery not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message.", "example": "Unauthorized" }, "code": { "description": "Machine-readable error code.", "example": "unauthorized", "type": "string" } }, "required": [ "error" ], "description": "Standard error body." } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:manage" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "example": "whep_01JXY9AZK4KV" }, "required": true, "description": "Webhook endpoint identifier." }, { "in": "path", "name": "deliveryId", "schema": { "type": "string", "example": "whdl_01JXY9AZK4KV" }, "required": true, "description": "Delivery identifier." } ] } } } }