{"openapi":"3.1.0","info":{"title":"MacroPrimer REST API","description":"The MacroPrimer REST API: manage a workspace's help-center content and read the\nknowledge base MacroPrimer builds from its code.\n\n**Authentication.** Every request carries a workspace API key as a bearer token —\n`Authorization: Bearer mp_live_…`. Create keys in the dashboard under\n**Settings → API keys** (workspace owners). A key addresses exactly one workspace.\n\n**Permissions.** Each endpoint requires one scope, listed on it; `GET /v1/me` needs\nnone and tells you which scopes your key holds.\n\n**Pagination.** List endpoints take `limit` (1–100) and `offset` and return\n`{\"data\": [...], \"pagination\": {\"limit\", \"offset\", \"total\", \"has_more\"}}`.\n\n**Errors.** Always `{\"error\": {\"type\", \"status\", \"message\"}}`; branch on `type`.\n\n**Rate limits.** Per workspace, by plan. Every response carries `X-RateLimit-Limit`,\n`X-RateLimit-Remaining` and `X-RateLimit-Reset`; a 429 adds `Retry-After`.\n","version":"1.0.0"},"servers":[{"url":"https://api.macroprimer.com"}],"paths":{"/v1/me":{"get":{"tags":["meta"],"summary":"Introspect the current API key","description":"**Required scope:** none — any valid API key.\n\nIdentify the calling key and the workspace it is bound to.\n\nRequires no scope — any valid key can ask what it is. It returns nothing the\nholder does not already possess, and refusing would make debugging a\nmisconfigured key needlessly hard.","operationId":"me_v1_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}}},"x-required-scope":null}},"/v1/scopes":{"get":{"tags":["meta"],"summary":"List available scopes","description":"**Required scope:** none — any valid API key.\n\nEvery scope this API defines, with what it permits.","operationId":"scopes_v1_scopes_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopeList"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}}},"x-required-scope":null}},"/v1/articles":{"get":{"tags":["articles"],"summary":"List articles","description":"**Required scope:** `articles:read`\n\nPaginated articles for one language, newest-updated first.","operationId":"list_articles_v1_articles_get","parameters":[{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Language variant to list. Defaults to the workspace default.","title":"Language"},"description":"Language variant to list. Defaults to the workspace default."},{"name":"collection_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only articles in this collection.","title":"Collection Id"},"description":"Only articles in this collection."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`draft` or `published`.","title":"Status"},"description":"`draft` or `published`."},{"name":"group_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"All variants of one logical article.","title":"Group Id"},"description":"All variants of one logical article."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Case-insensitive match on title, excerpt or body.","title":"Q"},"description":"Case-insensitive match on title, excerpt or body."},{"name":"updated_since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"ISO-8601. Only articles modified at or after this instant — use for incremental sync.","title":"Updated Since"},"description":"ISO-8601. Only articles modified at or after this instant — use for incremental sync."},{"name":"include_body","in":"query","required":false,"schema":{"type":"boolean","description":"Include full article bodies in the list response.","default":false,"title":"Include Body"},"description":"Include full article bodies in the list response."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Items per page (max 100).","default":25,"title":"Limit"},"description":"Items per page (max 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Items to skip.","default":0,"title":"Offset"},"description":"Items to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleList"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"articles:read"},"post":{"tags":["articles"],"summary":"Create an article","description":"**Required scope:** `articles:write`\n\nCreate an article, or a translation variant of an existing one.\n\nPublishing on create counts against the workspace's plan article cap and can\nreturn 402.","operationId":"create_article_v1_articles_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"402":{"description":"The workspace's plan does not allow this (limit reached, feature not included, or this month's AI allowance used up).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"payment_required","status":402,"message":"Publishing more articles requires the Pro plan or higher."}}}}},"409":{"description":"Conflicts with existing state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"conflict","status":409,"message":"a es variant of this article already exists"}}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"articles:write"}},"/v1/articles/{article_id}":{"get":{"tags":["articles"],"summary":"Retrieve an article","operationId":"get_article_v1_articles__article_id__get","parameters":[{"name":"article_id","in":"path","required":true,"schema":{"type":"string","title":"Article Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"articles:read","description":"**Required scope:** `articles:read`"},"patch":{"tags":["articles"],"summary":"Update an article","description":"**Required scope:** `articles:write`\n\nPartial update. Each successful call appends a revision, so history is\ncomplete whether an edit came from the dashboard or the API.","operationId":"update_article_v1_articles__article_id__patch","parameters":[{"name":"article_id","in":"path","required":true,"schema":{"type":"string","title":"Article Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"402":{"description":"The workspace's plan does not allow this (limit reached, feature not included, or this month's AI allowance used up).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"payment_required","status":402,"message":"Publishing more articles requires the Pro plan or higher."}}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"articles:write"},"delete":{"tags":["articles"],"summary":"Delete an article","description":"**Required scope:** `articles:write`\n\nDelete one language variant. Other variants in the group are untouched.","operationId":"delete_article_v1_articles__article_id__delete","parameters":[{"name":"article_id","in":"path","required":true,"schema":{"type":"string","title":"Article Id"}}],"responses":{"204":{"description":"Successful Response","headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"articles:write"}},"/v1/articles/{article_id}/publish":{"post":{"tags":["articles"],"summary":"Publish an article","description":"**Required scope:** `articles:write`\n\nIdempotent: publishing an already-published article is a no-op 200.","operationId":"publish_article_v1_articles__article_id__publish_post","parameters":[{"name":"article_id","in":"path","required":true,"schema":{"type":"string","title":"Article Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"402":{"description":"The workspace's plan does not allow this (limit reached, feature not included, or this month's AI allowance used up).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"payment_required","status":402,"message":"Publishing more articles requires the Pro plan or higher."}}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"articles:write"}},"/v1/articles/{article_id}/unpublish":{"post":{"tags":["articles"],"summary":"Unpublish an article","description":"**Required scope:** `articles:write`\n\nReturn an article to draft. It disappears from the public help center\nimmediately; nothing is deleted.","operationId":"unpublish_article_v1_articles__article_id__unpublish_post","parameters":[{"name":"article_id","in":"path","required":true,"schema":{"type":"string","title":"Article Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"articles:write"}},"/v1/articles/{article_id}/revisions":{"get":{"tags":["articles"],"summary":"List article revisions","description":"**Required scope:** `articles:read`\n\nVersion history, newest first. Bodies are omitted; fetch a single\nrevision for its content.","operationId":"list_revisions_v1_articles__article_id__revisions_get","parameters":[{"name":"article_id","in":"path","required":true,"schema":{"type":"string","title":"Article Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Items per page (max 100).","default":25,"title":"Limit"},"description":"Items per page (max 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Items to skip.","default":0,"title":"Offset"},"description":"Items to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevisionList"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"articles:read"}},"/v1/articles/{article_id}/revisions/{rev_id}":{"get":{"tags":["articles"],"summary":"Retrieve a revision","operationId":"get_revision_v1_articles__article_id__revisions__rev_id__get","parameters":[{"name":"article_id","in":"path","required":true,"schema":{"type":"string","title":"Article Id"}},{"name":"rev_id","in":"path","required":true,"schema":{"type":"string","title":"Rev Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Revision"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"articles:read","description":"**Required scope:** `articles:read`"}},"/v1/articles/{article_id}/revisions/{rev_id}/restore":{"post":{"tags":["articles"],"summary":"Restore a revision","description":"**Required scope:** `articles:write`\n\nNon-destructive revert: the old content is copied onto the live article as\na NEW revision, so the version you reverted from is still in history.","operationId":"restore_revision_v1_articles__article_id__revisions__rev_id__restore_post","parameters":[{"name":"article_id","in":"path","required":true,"schema":{"type":"string","title":"Article Id"}},{"name":"rev_id","in":"path","required":true,"schema":{"type":"string","title":"Rev Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"articles:write"}},"/v1/collections":{"get":{"tags":["collections"],"summary":"List collections","description":"**Required scope:** `categories:read`\n\nCollections for one language, in display order.","operationId":"list_collections_v1_collections_get","parameters":[{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Language variant to list. Defaults to the workspace default.","title":"Language"},"description":"Language variant to list. Defaults to the workspace default."},{"name":"parent_group_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only children of this collection.","title":"Parent Group Id"},"description":"Only children of this collection."},{"name":"include_hidden","in":"query","required":false,"schema":{"type":"boolean","description":"Set false to omit collections hidden from the public help center.","default":true,"title":"Include Hidden"},"description":"Set false to omit collections hidden from the public help center."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Items per page (max 100).","default":25,"title":"Limit"},"description":"Items per page (max 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Items to skip.","default":0,"title":"Offset"},"description":"Items to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionList"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"categories:read"},"post":{"tags":["collections"],"summary":"Create a collection","operationId":"create_collection_v1_collections_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"categories:write","description":"**Required scope:** `categories:write`"}},"/v1/collections/tree":{"get":{"tags":["collections"],"summary":"Retrieve the collection tree","description":"**Required scope:** `categories:read`\n\nThe whole hierarchy in one call, nested by ``parent_group_id``.\n\nUnpaginated on purpose — a help center's collection tree is small, and a\nclient rendering navigation needs all of it at once.","operationId":"collection_tree_v1_collections_tree_get","parameters":[{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Language variant. Defaults to the workspace default.","title":"Language"},"description":"Language variant. Defaults to the workspace default."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionTree"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"categories:read"}},"/v1/collections/{collection_id}":{"get":{"tags":["collections"],"summary":"Retrieve a collection","operationId":"get_collection_v1_collections__collection_id__get","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","title":"Collection Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"categories:read","description":"**Required scope:** `categories:read`"},"patch":{"tags":["collections"],"summary":"Update a collection","operationId":"update_collection_v1_collections__collection_id__patch","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","title":"Collection Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"categories:write","description":"**Required scope:** `categories:write`"},"delete":{"tags":["collections"],"summary":"Delete a collection","description":"**Required scope:** `categories:write`\n\nArticles in the collection are NOT deleted — they become uncategorised.","operationId":"delete_collection_v1_collections__collection_id__delete","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","title":"Collection Id"}}],"responses":{"204":{"description":"Successful Response","headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"categories:write"}},"/v1/collections/reorder":{"post":{"tags":["collections"],"summary":"Reorder sibling collections","description":"**Required scope:** `categories:write`\n\nSet display order for a set of siblings, by ``group_id``.\n\nApplies to every language variant of each group, so the public help center\n(which orders by the default-language rows) reflects the change at once.","operationId":"reorder_collections_v1_collections_reorder_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReorderIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Reordered"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"categories:write"}},"/v1/articles/{group_id}/comments":{"get":{"tags":["comments"],"summary":"List comments on an article","description":"**Required scope:** `comments:read`\n\nOpen comments first, then newest — the order a review queue reads in.\n\n``group_id`` is the article's logical id (its ``group_id`` field), which is\nshared by every language variant.","operationId":"list_comments_v1_articles__group_id__comments_get","parameters":[{"name":"group_id","in":"path","required":true,"schema":{"type":"string","title":"Group Id"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`open` or `resolved`.","title":"Status"},"description":"`open` or `resolved`."},{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`comment` or `finding`.","title":"Kind"},"description":"`comment` or `finding`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Items per page (max 100).","default":25,"title":"Limit"},"description":"Items per page (max 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Items to skip.","default":0,"title":"Offset"},"description":"Items to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentList"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"comments:read"},"post":{"tags":["comments"],"summary":"Comment on an article","operationId":"create_comment_v1_articles__group_id__comments_post","parameters":[{"name":"group_id","in":"path","required":true,"schema":{"type":"string","title":"Group Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comment"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"comments:write","description":"**Required scope:** `comments:write`"}},"/v1/comments/{comment_id}":{"patch":{"tags":["comments"],"summary":"Edit or resolve a comment","operationId":"update_comment_v1_comments__comment_id__patch","parameters":[{"name":"comment_id","in":"path","required":true,"schema":{"type":"string","title":"Comment Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comment"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"comments:write","description":"**Required scope:** `comments:write`"},"delete":{"tags":["comments"],"summary":"Delete a comment","operationId":"delete_comment_v1_comments__comment_id__delete","parameters":[{"name":"comment_id","in":"path","required":true,"schema":{"type":"string","title":"Comment Id"}}],"responses":{"204":{"description":"Successful Response","headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"comments:write","description":"**Required scope:** `comments:write`"}},"/v1/search":{"get":{"tags":["search"],"summary":"Search the knowledge base","description":"**Required scope:** `search:read`\n\nRanked results across articles and collections in one language.","operationId":"search_v1_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"description":"Search terms (minimum 2 characters).","title":"Q"},"description":"Search terms (minimum 2 characters)."},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Language to search. Defaults to the workspace default.","title":"Language"},"description":"Language to search. Defaults to the workspace default."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Restrict articles to `draft` or `published`.","title":"Status"},"description":"Restrict articles to `draft` or `published`."},{"name":"include_collections","in":"query","required":false,"schema":{"type":"boolean","description":"Also match collection names and descriptions.","default":true,"title":"Include Collections"},"description":"Also match collection names and descriptions."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResults"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"search:read"}},"/v1/translations/status":{"get":{"tags":["translations"],"summary":"Translation availability","description":"**Required scope:** `workspace:read`\n\nWhether translation can run, and which languages are available.","operationId":"translation_status_v1_translations_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslationStatus"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"workspace:read"}},"/v1/articles/{article_id}/translate":{"post":{"tags":["translations"],"summary":"Translate an article","description":"**Required scope:** `translations:write`\n\nTranslate an article into one or more active languages.\n\nSynchronous, and each language is a model call — expect seconds per target,\nand request a handful at a time rather than the whole language set at once.\nPer-language ``status`` is ``created``, ``updated`` or ``skipped``.","operationId":"translate_article_v1_articles__article_id__translate_post","parameters":[{"name":"article_id","in":"path","required":true,"schema":{"type":"string","title":"Article Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslateIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslationResult"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"402":{"description":"The workspace's plan does not allow this (limit reached, feature not included, or this month's AI allowance used up).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"payment_required","status":402,"message":"Publishing more articles requires the Pro plan or higher."}}}}},"503":{"description":"Unavailable: AI features can't run on this deployment right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"service_unavailable","status":503,"message":"AI features are not available on this deployment right now"}}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"translations:write"}},"/v1/collections/{collection_id}/translate":{"post":{"tags":["translations"],"summary":"Translate a collection","description":"**Required scope:** `translations:write`\n\nTranslate a collection's name and description into active languages.","operationId":"translate_collection_v1_collections__collection_id__translate_post","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","title":"Collection Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslateIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslationResult"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"402":{"description":"The workspace's plan does not allow this (limit reached, feature not included, or this month's AI allowance used up).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"payment_required","status":402,"message":"Publishing more articles requires the Pro plan or higher."}}}}},"503":{"description":"Unavailable: AI features can't run on this deployment right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"service_unavailable","status":503,"message":"AI features are not available on this deployment right now"}}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"translations:write"}},"/v1/knowledge/map":{"get":{"tags":["knowledge"],"summary":"Retrieve the product map","description":"**Required scope:** `knowledge:read`\n\nThe workspace's structured product knowledge.\n\n``exists: false`` (with 200, not 404) when the map has never been built, so a\nclient can degrade gracefully rather than treat it as an error.","operationId":"get_map_v1_knowledge_map_get","parameters":[{"name":"include","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated sections to return: overview, navigation, features, use_cases, glossary. Default: all.","title":"Include"},"description":"Comma-separated sections to return: overview, navigation, features, use_cases, glossary. Default: all."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductMap"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"knowledge:read"}},"/v1/knowledge/status":{"get":{"tags":["knowledge"],"summary":"Knowledge base status","description":"**Required scope:** `knowledge:read`\n\nCheap state check: does a map exist, at what version, how big is it.","operationId":"kb_status_v1_knowledge_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbStatus"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"knowledge:read"}},"/v1/knowledge/jobs":{"get":{"tags":["knowledge"],"summary":"List knowledge jobs","operationId":"list_jobs_v1_knowledge_jobs_get","parameters":[{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by job kind.","title":"Kind"},"description":"Filter by job kind."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`running`, `done`, `error` or `canceled`.","title":"Status"},"description":"`running`, `done`, `error` or `canceled`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Items per page (max 100).","default":25,"title":"Limit"},"description":"Items per page (max 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Items to skip.","default":0,"title":"Offset"},"description":"Items to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbJobList"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"knowledge:read","description":"**Required scope:** `knowledge:read`"},"post":{"tags":["knowledge"],"summary":"Start a knowledge job","description":"**Required scope:** `knowledge:write`\n\nStart a build or drafting run over the workspace's connected repositories.\n\n202 with the job to poll. Idempotent per (workspace, kind) while one runs:\nthe in-flight job is returned instead of a second one being started.","operationId":"start_job_v1_knowledge_jobs_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStart"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbJob"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"402":{"description":"The workspace's plan does not allow this (limit reached, feature not included, or this month's AI allowance used up).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"payment_required","status":402,"message":"Publishing more articles requires the Pro plan or higher."}}}}},"503":{"description":"Unavailable: AI features can't run on this deployment right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"service_unavailable","status":503,"message":"AI features are not available on this deployment right now"}}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"knowledge:write"}},"/v1/knowledge/jobs/{job_id}":{"get":{"tags":["knowledge"],"summary":"Retrieve a job","operationId":"get_job_v1_knowledge_jobs__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbJob"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"knowledge:read","description":"**Required scope:** `knowledge:read`"}},"/v1/knowledge/profile":{"get":{"tags":["knowledge"],"summary":"Retrieve the product profile","description":"**Required scope:** `knowledge:read`\n\nWho the knowledge base is written for (``audience``: end_user, developer or\ndata_practitioner) and how finely it is itemised (``granularity``:\nconsolidated or per_surface), whether it was set explicitly, and what the\nconnected repositories suggest. Unset workspaces use the default profile.","operationId":"get_profile_v1_knowledge_profile_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductProfile"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"knowledge:read"},"put":{"tags":["knowledge"],"summary":"Set the product profile","description":"**Required scope:** `knowledge:write`\n\nTakes effect from the next ``build`` job; the current knowledge map is unchanged.","operationId":"set_profile_v1_knowledge_profile_put","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbProfile"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductProfile"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"knowledge:write"},"delete":{"tags":["knowledge"],"summary":"Reset the product profile to the default","operationId":"reset_profile_v1_knowledge_profile_delete","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductProfile"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"knowledge:write","description":"**Required scope:** `knowledge:write`"}},"/v1/knowledge/jobs/{job_id}/cancel":{"post":{"tags":["knowledge"],"summary":"Cancel a job","operationId":"cancel_job_v1_knowledge_jobs__job_id__cancel_post","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbJob"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"knowledge:write","description":"**Required scope:** `knowledge:write`"}},"/v1/knowledge/suggestions":{"get":{"tags":["knowledge"],"summary":"List article suggestions","description":"**Required scope:** `knowledge:read`\n\nAI-drafted articles awaiting review. Nothing here is live content until\nit is accepted.","operationId":"list_suggestions_v1_knowledge_suggestions_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`pending`, `accepted` or `dismissed`.","default":"pending","title":"Status"},"description":"`pending`, `accepted` or `dismissed`."},{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`new` or `update`.","title":"Kind"},"description":"`new` or `update`."},{"name":"include_body","in":"query","required":false,"schema":{"type":"boolean","description":"Include full drafted bodies.","default":false,"title":"Include Body"},"description":"Include full drafted bodies."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Items per page (max 100).","default":25,"title":"Limit"},"description":"Items per page (max 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Items to skip.","default":0,"title":"Offset"},"description":"Items to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuggestionList"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"knowledge:read"}},"/v1/knowledge/suggestions/{suggestion_id}":{"get":{"tags":["knowledge"],"summary":"Retrieve a suggestion","operationId":"get_suggestion_v1_knowledge_suggestions__suggestion_id__get","parameters":[{"name":"suggestion_id","in":"path","required":true,"schema":{"type":"string","title":"Suggestion Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suggestion"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"knowledge:read","description":"**Required scope:** `knowledge:read`"}},"/v1/knowledge/suggestions/{suggestion_id}/dismiss":{"post":{"tags":["knowledge"],"summary":"Dismiss a suggestion","description":"**Required scope:** `knowledge:write`\n\nTake a draft out of the review queue without publishing it.","operationId":"dismiss_suggestion_v1_knowledge_suggestions__suggestion_id__dismiss_post","parameters":[{"name":"suggestion_id","in":"path","required":true,"schema":{"type":"string","title":"Suggestion Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suggestion"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"knowledge:write"}},"/v1/knowledge/overview":{"get":{"tags":["knowledge"],"summary":"Overview, navigation and counts","description":"**Required scope:** `knowledge:read`\n\nThe live map's overview and navigation, the product profile, and how many\nitems and surfaces it holds. ``exists`` is false until a map has been built.","operationId":"get_overview_v1_knowledge_overview_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Overview"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"knowledge:read"}},"/v1/knowledge/items":{"get":{"tags":["knowledge"],"summary":"List knowledge items","operationId":"list_items_v1_knowledge_items_get","parameters":[{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"enum":["feature","use_case","term"],"type":"string"},{"type":"null"}],"description":"Only items of this kind.","title":"Kind"},"description":"Only items of this kind."},{"name":"surface","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only items that document this surface key.","title":"Surface"},"description":"Only items that document this surface key."},{"name":"publishable","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Only items that may (or may not) become public articles.","title":"Publishable"},"description":"Only items that may (or may not) become public articles."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Items per page (max 100).","default":25,"title":"Limit"},"description":"Items per page (max 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Items to skip.","default":0,"title":"Offset"},"description":"Items to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbItemList"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"knowledge:read","description":"**Required scope:** `knowledge:read`"}},"/v1/knowledge/items/{key}":{"get":{"tags":["knowledge"],"summary":"Retrieve a knowledge item","description":"**Required scope:** `knowledge:read`\n\nOne item with ``related`` items (``related``: same source area;\n``mentions``: a glossary term that appears in it) and ``surface_details`` for\nthe surfaces it documents.","operationId":"get_item_v1_knowledge_items__key__get","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","title":"Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbItemDetail"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"knowledge:read"}},"/v1/knowledge/surfaces":{"get":{"tags":["knowledge"],"summary":"List surfaces found in the code","description":"**Required scope:** `knowledge:read`\n\nEach surface lists the items that document it (``documented_by``); an empty\nlist is a documentation gap.","operationId":"list_surfaces_v1_knowledge_surfaces_get","parameters":[{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"enum":["screen","route","endpoint","command","symbol","pipeline","notebook","table"],"type":"string"},{"type":"null"}],"description":"Only surfaces of this kind.","title":"Kind"},"description":"Only surfaces of this kind."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Substring of the name or label.","title":"Q"},"description":"Substring of the name or label."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Items per page (max 100).","default":25,"title":"Limit"},"description":"Items per page (max 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Items to skip.","default":0,"title":"Offset"},"description":"Items to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurfaceList"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"knowledge:read"}},"/v1/knowledge/surfaces/{key}":{"get":{"tags":["knowledge"],"summary":"Retrieve a surface with its detail sheet","description":"**Required scope:** `knowledge:read`\n\nOne surface, the items documenting it, and its ``sheet``: what it looks like\nand does — for a screen its layout, fields, actions, states and permissions;\nfor an endpoint its parameters and responses — written from its code.","operationId":"get_surface_v1_knowledge_surfaces__key__get","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","title":"Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurfaceDetail"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"knowledge:read"}},"/v1/knowledge/search":{"get":{"tags":["knowledge"],"summary":"Search knowledge items","description":"**Required scope:** `knowledge:read`\n\nRanked full-text search in the workspace's language (title first, then\nsummary and location, then detail and steps).","operationId":"search_v1_knowledge_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"description":"Search terms.","title":"Q"},"description":"Search terms."},{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"enum":["feature","use_case","term"],"type":"string"},{"type":"null"}],"title":"Kind"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":10,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbItemSearch"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"knowledge:read"}},"/v1/knowledge/export":{"get":{"tags":["knowledge"],"summary":"Export the whole knowledge base","description":"**Required scope:** `knowledge:read`\n\nThe live map in MacroPrimer's own format (``macroprimer.knowledge/v1``):\noverview, navigation, profile, items, links and surfaces. ``markdown`` returns\nREADME.md, items/<kind>/<name>.md with YAML front matter, and knowledge.json.\n\nSends an ``ETag`` per map version and format; a matching ``If-None-Match``\nreturns 304, so a syncing client downloads only when the map changed.","operationId":"export_v1_knowledge_export_get","parameters":[{"name":"format","in":"query","required":false,"schema":{"enum":["json","markdown"],"type":"string","description":"json, or markdown (a .tar.gz of files).","default":"json","title":"Format"},"description":"json, or markdown (a .tar.gz of files)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeExport"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"knowledge:read"}},"/v1/knowledge/audit":{"get":{"tags":["knowledge"],"summary":"Deterministic health checks","description":"**Required scope:** `knowledge:read`\n\nBroken links, cited surfaces that no longer exist, items whose source code\nchanged since the map was built, items without a source, and surfaces nothing\ndocuments (with ``surface_coverage``). ``healthy`` is false when anything needs\naction; coverage gaps alone do not make it false.","operationId":"audit_v1_knowledge_audit_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Audit"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"knowledge:read"}},"/v1/walkthroughs":{"get":{"tags":["walkthroughs"],"summary":"List walkthrough jobs","operationId":"list_jobs_v1_walkthroughs_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`queued`, `running`, `done` or `failed`.","title":"Status"},"description":"`queued`, `running`, `done` or `failed`."},{"name":"group_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Jobs for one article group.","title":"Group Id"},"description":"Jobs for one article group."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Items per page (max 100).","default":25,"title":"Limit"},"description":"Items per page (max 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Items to skip.","default":0,"title":"Offset"},"description":"Items to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalkthroughJobList"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"walkthroughs:read","description":"**Required scope:** `walkthroughs:read`"},"post":{"tags":["walkthroughs"],"summary":"Enqueue walkthroughs","description":"**Required scope:** `walkthroughs:write`\n\nQueue walkthrough generation for a set of articles.\n\nArticles already queued or running are skipped rather than duplicated, so\nre-sending the same request is safe.","operationId":"enqueue_v1_walkthroughs_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnqueueIn"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Enqueued"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"walkthroughs:write"}},"/v1/walkthroughs/coverage":{"get":{"tags":["walkthroughs"],"summary":"Walkthrough coverage by article","description":"**Required scope:** `walkthroughs:read`\n\nBest-known state per article group: ``done`` > ``running`` > ``queued`` >\n``failed``. One call to answer 'which articles still need a walkthrough'.","operationId":"coverage_v1_walkthroughs_coverage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Coverage"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"walkthroughs:read"}},"/v1/walkthroughs/{job_id}":{"get":{"tags":["walkthroughs"],"summary":"Retrieve a walkthrough job","operationId":"get_job_v1_walkthroughs__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalkthroughJob"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"walkthroughs:read","description":"**Required scope:** `walkthroughs:read`"}},"/v1/walkthroughs/retry":{"post":{"tags":["walkthroughs"],"summary":"Retry a walkthrough","description":"**Required scope:** `walkthroughs:write`\n\nRe-run one article's walkthrough. No-op when one is already in flight.","operationId":"retry_v1_walkthroughs_retry_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetryIn"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueueState"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"walkthroughs:write"}},"/v1/assets":{"get":{"tags":["assets"],"summary":"List assets","description":"**Required scope:** `assets:read`\n\nThe media library, newest first.","operationId":"list_assets_v1_assets_get","parameters":[{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`image`, `file` or `raw_article`.","title":"Kind"},"description":"`image`, `file` or `raw_article`."},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Provenance, e.g. `upload`, `intercom`, `walkthrough`.","title":"Source"},"description":"Provenance, e.g. `upload`, `intercom`, `walkthrough`."},{"name":"article_group_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Assets linked to one article group.","title":"Article Group Id"},"description":"Assets linked to one article group."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Items per page (max 100).","default":25,"title":"Limit"},"description":"Items per page (max 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Items to skip.","default":0,"title":"Offset"},"description":"Items to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetList"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"assets:read"},"post":{"tags":["assets"],"summary":"Upload an image","description":"**Required scope:** `assets:write`\n\nUpload image bytes as the raw request body.\n\nSend the format in ``Content-Type`` (PNG, JPEG, SVG, WEBP or GIF, max 5 MB).\nThe returned ``url`` is stable and safe to embed in article HTML.","operationId":"upload_asset_v1_assets_post","responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"413":{"description":"Payload too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"payload_too_large","status":413,"message":"file too large"}}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"assets:write"}},"/v1/assets/{asset_id}":{"get":{"tags":["assets"],"summary":"Retrieve an asset","description":"**Required scope:** `assets:read`\n\nFull record including stored content for ``raw_article`` assets.","operationId":"get_asset_v1_assets__asset_id__get","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","title":"Asset Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"assets:read"},"delete":{"tags":["assets"],"summary":"Delete an asset","description":"**Required scope:** `assets:write`\n\nRemoves the record and, for media, the stored file. Articles embedding it\nare not rewritten — their images will 404, so check usage first.","operationId":"delete_asset_v1_assets__asset_id__delete","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","title":"Asset Id"}}],"responses":{"204":{"description":"Successful Response","headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"not_found","status":404,"message":"article not found"}}}}}},"x-required-scope":"assets:write"}},"/v1/workspace":{"get":{"tags":["workspace"],"summary":"Retrieve the workspace","description":"**Required scope:** `workspace:read`\n\nIdentity, help-center URL, languages and plan for the key's workspace.","operationId":"get_workspace_v1_workspace_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"workspace:read"},"patch":{"tags":["workspace"],"summary":"Update the workspace","description":"**Required scope:** `workspace:write`\n\nRename the workspace or point a custom domain at its help center.\n\nThe ``slug`` is deliberately not editable here: it is part of the public\nhelp-center URL, and changing it breaks every published link. Change it from\nthe dashboard, where the consequence is spelled out.","operationId":"update_workspace_v1_workspace_patch","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"402":{"description":"The workspace's plan does not allow this (limit reached, feature not included, or this month's AI allowance used up).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"payment_required","status":402,"message":"Publishing more articles requires the Pro plan or higher."}}}}},"409":{"description":"Conflicts with existing state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"conflict","status":409,"message":"a es variant of this article already exists"}}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"workspace:write"}},"/v1/workspace/branding":{"get":{"tags":["workspace"],"summary":"Retrieve help-center branding","operationId":"get_branding_v1_workspace_branding_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Branding"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"workspace:read","description":"**Required scope:** `workspace:read`"},"patch":{"tags":["workspace"],"summary":"Update help-center branding","description":"**Required scope:** `workspace:write`\n\nColours and logo for the public help center. Omitted fields keep their\ncurrent value; an explicit null resets one to its default.","operationId":"update_branding_v1_workspace_branding_patch","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandingUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Branding"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"workspace:write"}},"/v1/workspace/languages":{"get":{"tags":["workspace"],"summary":"Retrieve languages","description":"**Required scope:** `workspace:read`\n\nActive languages, the default (source of truth), and every option.","operationId":"get_languages_v1_workspace_languages_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Languages"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"workspace:read"},"patch":{"tags":["workspace"],"summary":"Update languages","description":"**Required scope:** `workspace:write`\n\nChange which languages the help center publishes.\n\nThe default language is the source of truth for structure and search, so it\nis always forced into the active set rather than being droppable by\nomission.","operationId":"update_languages_v1_workspace_languages_patch","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LanguagesUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LanguagesSet"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"402":{"description":"The workspace's plan does not allow this (limit reached, feature not included, or this month's AI allowance used up).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"payment_required","status":402,"message":"Publishing more articles requires the Pro plan or higher."}}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"workspace:write"}},"/v1/workspace/stats":{"get":{"tags":["workspace"],"summary":"Content statistics","description":"**Required scope:** `workspace:read`\n\nCounts for the workspace's content, in the default language.","operationId":"stats_v1_workspace_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stats"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"workspace:read"}},"/v1/knowledge/action/session":{"post":{"tags":["knowledge"],"summary":"Start a GitHub Action run","description":"**Required scope:** `knowledge:ingest`\n\nWhat a GitHub Action run needs before it reads the repository: the profile\nto read it for, what is already current, the models it may use, and what is\nleft of this month's allowance. No model access yet — see ``/token``.\n\n409 when the repository is connected with a token instead.","operationId":"start_session_v1_knowledge_action_session_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionSession"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"402":{"description":"The workspace's plan does not allow this (limit reached, feature not included, or this month's AI allowance used up).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"payment_required","status":402,"message":"Publishing more articles requires the Pro plan or higher."}}}}},"409":{"description":"Conflicts with existing state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"conflict","status":409,"message":"a es variant of this article already exists"}}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"knowledge:ingest"}},"/v1/knowledge/action/token":{"post":{"tags":["knowledge"],"summary":"Get model access for a GitHub Action run","description":"**Required scope:** `knowledge:ingest`\n\nA token capped at what the reported work can cost. Asked for only when a\nrun has something to rewrite.\n\n402 when the work doesn't fit what is left of this month's budget; 409 when\nthe repository is connected with a token instead.","operationId":"issue_token_v1_knowledge_action_token_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionToken"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"402":{"description":"The workspace's plan does not allow this (limit reached, feature not included, or this month's AI allowance used up).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"payment_required","status":402,"message":"Publishing more articles requires the Pro plan or higher."}}}}},"409":{"description":"Conflicts with existing state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"conflict","status":409,"message":"a es variant of this article already exists"}}}}},"503":{"description":"Unavailable: AI features can't run on this deployment right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"service_unavailable","status":503,"message":"AI features are not available on this deployment right now"}}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"knowledge:ingest"}},"/v1/knowledge/action/bundle":{"put":{"tags":["knowledge"],"summary":"Upload what a GitHub Action run derived","description":"**Required scope:** `knowledge:ingest`\n\nStore a run's file hashes, capsules, UI strings, surfaces and sheets as the\nrepository's current state, then start a build unless ``build`` is false.\n\n409 when the repository is connected with a token, or when the run kept\nsomething the server no longer has (another run landed first): re-run it.\n422 when a sheet was not written for its surface's current code and the\nworkspace's audience.","operationId":"upload_bundle_v1_knowledge_action_bundle_put","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bundle"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionUpload"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"409":{"description":"Conflicts with existing state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"conflict","status":409,"message":"a es variant of this article already exists"}}}}},"422":{"description":"Invalid request: the `fields` list says which field and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"invalid_request","status":422,"message":"one or more fields are invalid","fields":[{"field":"title","reason":"String should have at least 1 character"}]}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"unauthorized","status":401,"message":"invalid or inactive API key"}}}}},"429":{"description":"Rate limit reached for the workspace's plan; retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"rate_limited","status":429,"message":"rate limit exceeded for this workspace's plan"}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per window for the workspace's plan.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix time when the window resets.","schema":{"type":"string"}}}},"403":{"description":"The API key lacks the scope this endpoint requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"type":"forbidden","status":403,"message":"this API key is missing the required scope: articles:write"}}}}}},"x-required-scope":"knowledge:ingest"}}},"components":{"schemas":{"ActionSession":{"properties":{"source_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Id","description":"The repository's source, once a first upload created it."},"profile":{"$ref":"#/components/schemas/SessionProfile","description":"The workspace's product profile: what to read the code for."},"dirs":{"additionalProperties":{"type":"string"},"type":"object","title":"Dirs","description":"Digest of each stored capsule; matching areas are kept, not re-read."},"sheets":{"additionalProperties":{"type":"string"},"type":"object","title":"Sheets","description":"Digest of each stored sheet; matching surfaces are kept."},"ai":{"$ref":"#/components/schemas/SessionAi"},"budget":{"$ref":"#/components/schemas/SessionBudget"}},"additionalProperties":false,"type":"object","required":["source_id","profile","dirs","sheets","ai","budget"],"title":"ActionSession","examples":[{"ai":{"base_url":"https://api.deepinfra.com/v1/openai","models":{"fast":"provider/model","main":"provider/model"},"provider":"deepinfra"},"budget":{"monthly_usd":20.0,"remaining_usd":18.4},"dirs":{"src/pages":"1111111111111111111111111111111111111111111111111111111111111111"},"profile":{"audience":"end_user","granularity":"consolidated","surface_kinds":["screen"]},"sheets":{"screen:/invoices":"3333333333333333333333333333333333333333333333333333333333333333"},"source_id":"src_1…"}]},"ActionToken":{"properties":{"token":{"type":"string","title":"Token","description":"Limited to the session's models. Mask it in logs."},"expires_in":{"type":"integer","title":"Expires In","description":"Seconds until the token stops working."},"spending_limit_usd":{"type":"number","title":"Spending Limit Usd"}},"additionalProperties":false,"type":"object","required":["token","expires_in","spending_limit_usd"],"title":"ActionToken","examples":[{"expires_in":7200,"spending_limit_usd":0.17,"token":"jwt:…"}]},"ActionUpload":{"properties":{"source_id":{"type":"string","title":"Source Id"},"job":{"anyOf":[{"$ref":"#/components/schemas/KbJob"},{"type":"null"}],"description":"The build started from this upload, if one was."},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"}},"additionalProperties":false,"type":"object","required":["source_id","job","warnings"],"title":"ActionUpload","examples":[{"source_id":"src_1…","warnings":[]}]},"Article":{"properties":{"id":{"type":"string","title":"Id"},"group_id":{"type":"string","title":"Group Id","description":"Shared by every language variant of the same logical article — key syncs on it."},"title":{"type":"string","title":"Title"},"slug":{"type":"string","title":"Slug"},"excerpt":{"type":"string","title":"Excerpt"},"status":{"type":"string","enum":["draft","published"],"title":"Status"},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id"},"order":{"type":"integer","title":"Order"},"language":{"type":"string","title":"Language"},"origin":{"type":"string","title":"Origin","description":"Where it came from: `manual`, `api`, `intercom`, `suggested`, …"},"translation":{"$ref":"#/components/schemas/Translation"},"quality":{"$ref":"#/components/schemas/Quality"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"body":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body","description":"Sanitized HTML. Included on single-article responses, and on lists with `include_body=true`."}},"additionalProperties":false,"type":"object","required":["id","group_id","title","slug","excerpt","status","collection_id","order","language","origin","translation","quality","created_at","updated_at"],"title":"Article","examples":[{"body":"<p>Open <strong>Orders</strong>, filter the list, then choose <strong>Export</strong>.</p>","collection_id":"k3e2…","created_at":"2026-09-01T09:12:00+00:00","excerpt":"Download any filtered order list as a spreadsheet.","group_id":"g91c…","id":"a7d4…","language":"en","order":0,"origin":"api","quality":{"checked_at":"2026-09-30T10:00:00+00:00","flags":[],"score":92},"slug":"export-orders-to-csv","status":"published","title":"Export orders to CSV","translation":{"available_languages":["en","es"],"machine_translated":false,"stale":false},"updated_at":"2026-10-01T16:40:00+00:00"}]},"ArticleCreate":{"properties":{"title":{"type":"string","maxLength":300,"minLength":1,"title":"Title"},"body":{"type":"string","title":"Body","default":""},"excerpt":{"type":"string","title":"Excerpt","default":""},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id"},"status":{"type":"string","title":"Status","default":"draft"},"order":{"type":"integer","title":"Order","default":0},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Defaults to the workspace default language."},"group_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Group Id","description":"Attach as a translation variant of an existing article group."}},"type":"object","required":["title"],"title":"ArticleCreate","examples":[{"body":"<p>Open <strong>Orders</strong>, then choose <strong>Export</strong>.</p>","collection_id":"k3e2…","excerpt":"Download any filtered order list as a spreadsheet.","status":"draft","title":"Export orders to CSV"}]},"ArticleList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Article"},"type":"array","title":"Data"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"additionalProperties":false,"type":"object","required":["data","pagination"],"title":"ArticleList","examples":[{"data":[{"body":"<p>Open <strong>Orders</strong>, filter the list, then choose <strong>Export</strong>.</p>","collection_id":"k3e2…","created_at":"2026-09-01T09:12:00+00:00","excerpt":"Download any filtered order list as a spreadsheet.","group_id":"g91c…","id":"a7d4…","language":"en","order":0,"origin":"api","quality":{"checked_at":"2026-09-30T10:00:00+00:00","flags":[],"score":92},"slug":"export-orders-to-csv","status":"published","title":"Export orders to CSV","translation":{"available_languages":["en","es"],"machine_translated":false,"stale":false},"updated_at":"2026-10-01T16:40:00+00:00"}],"pagination":{"has_more":false,"limit":25,"offset":0,"total":1}}]},"ArticleUpdate":{"properties":{"title":{"anyOf":[{"type":"string","maxLength":300,"minLength":1},{"type":"null"}],"title":"Title"},"body":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Excerpt"},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"order":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Order"}},"type":"object","title":"ArticleUpdate","description":"Every field optional — only what you send is changed.","examples":[{"status":"published","title":"Export orders to CSV or Excel"}]},"Asset":{"properties":{"id":{"type":"string","title":"Id"},"kind":{"type":"string","title":"Kind","description":"`image`, `file`, `raw_article`, …"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename"},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type"},"size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Size Bytes"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Excerpt"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"`upload`, `intercom`, `walkthrough`, …"},"intercom_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intercom Id"},"article_group_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Article Group Id"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"Text content (for text kinds), on single-asset responses."}},"additionalProperties":false,"type":"object","required":["id","kind","title","url","filename","content_type","size_bytes","excerpt","source","intercom_id","article_group_id","created_at"],"title":"Asset","examples":[{"content_type":"image/png","created_at":"2026-10-01T12:00:00+00:00","filename":"orders.png","id":"as9f…","kind":"image","size_bytes":48211,"source":"upload","title":"Orders list","url":"/kb-asset/c1a2…/orders.png"}]},"AssetList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Asset"},"type":"array","title":"Data"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"additionalProperties":false,"type":"object","required":["data","pagination"],"title":"AssetList","examples":[{"data":[{"content_type":"image/png","created_at":"2026-10-01T12:00:00+00:00","filename":"orders.png","id":"as9f…","kind":"image","size_bytes":48211,"source":"upload","title":"Orders list","url":"/kb-asset/c1a2…/orders.png"}],"pagination":{"has_more":false,"limit":25,"offset":0,"total":1}}]},"Audit":{"properties":{"version":{"type":"integer","title":"Version"},"counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Counts"},"surface_coverage":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Surface Coverage","description":"Share of code surfaces at least one item documents."},"checks":{"$ref":"#/components/schemas/AuditChecks"},"totals":{"additionalProperties":{"type":"integer"},"type":"object","title":"Totals"},"healthy":{"type":"boolean","title":"Healthy","description":"No dangling links, missing surfaces or stale items."}},"additionalProperties":false,"type":"object","required":["version","counts","surface_coverage","checks","totals","healthy"],"title":"Audit","examples":[{"checks":{"dangling_links":[],"items_without_sources":[],"missing_surfaces":[],"stale_items":[],"undocumented_surfaces":[{"key":"route:/beta","kind":"route"}]},"counts":{"items":113,"links":240,"surfaces":94},"healthy":true,"surface_coverage":0.8723,"totals":{"dangling_links":0,"items_without_sources":0,"missing_surfaces":0,"stale_items":0,"undocumented_surfaces":1},"version":7}]},"AuditChecks":{"properties":{"dangling_links":{"items":{"type":"string"},"type":"array","title":"Dangling Links"},"missing_surfaces":{"items":{"type":"string"},"type":"array","title":"Missing Surfaces"},"stale_items":{"items":{"type":"string"},"type":"array","title":"Stale Items","description":"Items whose source code changed since they were built."},"items_without_sources":{"items":{"type":"string"},"type":"array","title":"Items Without Sources"},"undocumented_surfaces":{"items":{"$ref":"#/components/schemas/UndocumentedSurface"},"type":"array","title":"Undocumented Surfaces"}},"additionalProperties":false,"type":"object","required":["dangling_links","missing_surfaces","stale_items","items_without_sources","undocumented_surfaces"],"title":"AuditChecks"},"Branding":{"properties":{"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo Url"},"nav_color":{"type":"string","title":"Nav Color"},"hero_color":{"type":"string","title":"Hero Color"},"accent_color":{"type":"string","title":"Accent Color"},"hero_title":{"type":"string","title":"Hero Title"}},"additionalProperties":false,"type":"object","required":["logo_url","nav_color","hero_color","accent_color","hero_title"],"title":"Branding","examples":[{"accent_color":"#29C175","hero_color":"#30473F","hero_title":"How can we help?","logo_url":"/kb-asset/c1a2…/logo.png","nav_color":"#182328"}]},"BrandingUpdate":{"properties":{"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo Url"},"nav_color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nav Color","description":"CSS hex colour, e.g. #ffffff."},"hero_color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hero Color"},"accent_color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accent Color"},"hero_title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Hero Title"}},"type":"object","title":"BrandingUpdate","examples":[{"accent_color":"#29C175","hero_title":"How can we help?"}]},"Bundle":{"properties":{"repo":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$","title":"Repo","description":"`owner/repo` the run read."},"sha":{"type":"string","maxLength":64,"title":"Sha","description":"The commit the run read."},"branch":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Branch"},"files":{"items":{"$ref":"#/components/schemas/BundleFile"},"type":"array","maxItems":12000,"title":"Files","description":"Every file read: path and content hash, never contents."},"profile_detection":{"additionalProperties":true,"type":"object","title":"Profile Detection","description":"What kind of product the code looks like."},"dirs":{"items":{"$ref":"#/components/schemas/BundleDir"},"type":"array","maxItems":12000,"title":"Dirs"},"surfaces":{"items":{"$ref":"#/components/schemas/BundleSurface"},"type":"array","maxItems":3000,"title":"Surfaces"},"sheets":{"items":{"$ref":"#/components/schemas/BundleSheet"},"type":"array","maxItems":300,"title":"Sheets"},"build":{"type":"boolean","title":"Build","description":"Start a knowledge-base build once stored.","default":true}},"additionalProperties":false,"type":"object","required":["repo","sha","files","dirs","surfaces","sheets"],"title":"Bundle","examples":[{"branch":"main","build":true,"dirs":[{"capsule":"Lists invoices; filter by status.","digest":"1111111111111111111111111111111111111111111111111111111111111111","dir_path":"src/pages","ui_strings":["Invoices","Mark as paid"]}],"files":[{"path":"src/pages/Invoices.tsx","sha256":"0000000000000000000000000000000000000000000000000000000000000000"}],"profile_detection":{},"repo":"acme/shop","sha":"9f2c4e1","sheets":[{"digest":"3333333333333333333333333333333333333333333333333333333333333333","sheet":{"purpose":"Review and settle invoices."},"surface_key":"screen:/invoices"}],"surfaces":[{"file":"src/routes.tsx","framework":"react-router","key":"screen:/invoices","kind":"screen","label":"Invoices","name":"/invoices","sheet_digest":"2222222222222222222222222222222222222222222222222222222222222222","sheet_plan":[["src/pages/Invoices.tsx",false]],"target":"src/pages/Invoices.tsx"}]}]},"BundleDir":{"properties":{"dir_path":{"type":"string","maxLength":500,"title":"Dir Path"},"digest":{"type":"string","maxLength":64,"title":"Digest"},"keep":{"type":"boolean","title":"Keep","default":false},"capsule":{"anyOf":[{"type":"string","maxLength":50000},{"type":"null"}],"title":"Capsule"},"ui_strings":{"items":{"type":"string"},"type":"array","maxItems":2000,"title":"Ui Strings"}},"additionalProperties":false,"type":"object","required":["dir_path","digest"],"title":"BundleDir"},"BundleFile":{"properties":{"path":{"type":"string","maxLength":500,"title":"Path"},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","title":"Sha256"}},"additionalProperties":false,"type":"object","required":["path","sha256"],"title":"BundleFile"},"BundleSheet":{"properties":{"surface_key":{"type":"string","maxLength":2000,"title":"Surface Key"},"digest":{"type":"string","maxLength":64,"title":"Digest"},"keep":{"type":"boolean","title":"Keep","default":false},"sheet":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Sheet"}},"additionalProperties":false,"type":"object","required":["surface_key","digest"],"title":"BundleSheet"},"BundleSurface":{"properties":{"kind":{"type":"string","maxLength":16,"title":"Kind"},"key":{"type":"string","maxLength":2000,"title":"Key"},"name":{"type":"string","maxLength":2000,"title":"Name"},"label":{"type":"string","maxLength":500,"title":"Label","default":""},"file":{"type":"string","maxLength":500,"title":"File"},"framework":{"type":"string","maxLength":40,"title":"Framework","default":""},"target":{"type":"string","maxLength":2000,"title":"Target","default":""},"sheet_plan":{"items":{"prefixItems":[{"type":"string"},{"type":"boolean"}],"type":"array","maxItems":2,"minItems":2},"type":"array","maxItems":200,"title":"Sheet Plan"},"sheet_digest":{"type":"string","maxLength":64,"title":"Sheet Digest","default":""}},"additionalProperties":false,"type":"object","required":["kind","key","name","file"],"title":"BundleSurface"},"Collection":{"properties":{"id":{"type":"string","title":"Id"},"group_id":{"type":"string","title":"Group Id"},"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"description":{"type":"string","title":"Description"},"order":{"type":"integer","title":"Order"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url"},"hidden":{"type":"boolean","title":"Hidden","description":"Hidden from the public help-center home (still reachable by link and search)."},"is_section":{"type":"boolean","title":"Is Section","description":"Shown inline on its parent's page as a heading with its articles."},"parent_group_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Group Id","description":"The parent collection's group_id; null at the top level."},"language":{"type":"string","title":"Language"},"translation":{"$ref":"#/components/schemas/Translation"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"article_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Article Count","description":"Articles directly in this collection, on list responses."}},"additionalProperties":false,"type":"object","required":["id","group_id","name","slug","description","order","image_url","hidden","is_section","parent_group_id","language","translation","created_at"],"title":"Collection","examples":[{"created_at":"2026-09-01T09:00:00+00:00","description":"Finding, filtering and exporting orders.","group_id":"cg81…","hidden":false,"id":"k3e2…","is_section":false,"language":"en","name":"Orders","order":0,"slug":"orders","translation":{"available_languages":["en"],"machine_translated":false,"stale":false}}]},"CollectionCreate":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name"},"description":{"type":"string","title":"Description","default":""},"order":{"type":"integer","title":"Order","default":0},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url"},"hidden":{"type":"boolean","title":"Hidden","default":false},"is_section":{"type":"boolean","title":"Is Section","default":false},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"group_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Group Id","description":"Attach as a translation variant of an existing collection."},"parent_group_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Group Id","description":"group_id of the parent collection; null = top level."}},"type":"object","required":["name"],"title":"CollectionCreate","examples":[{"description":"Finding, filtering and exporting orders.","name":"Orders"}]},"CollectionList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Collection"},"type":"array","title":"Data"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"additionalProperties":false,"type":"object","required":["data","pagination"],"title":"CollectionList","examples":[{"data":[{"article_count":4,"created_at":"2026-09-01T09:00:00+00:00","description":"Finding, filtering and exporting orders.","group_id":"cg81…","hidden":false,"id":"k3e2…","is_section":false,"language":"en","name":"Orders","order":0,"slug":"orders","translation":{"available_languages":["en"],"machine_translated":false,"stale":false}}],"pagination":{"has_more":false,"limit":25,"offset":0,"total":1}}]},"CollectionNode":{"properties":{"id":{"type":"string","title":"Id"},"group_id":{"type":"string","title":"Group Id"},"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"description":{"type":"string","title":"Description"},"order":{"type":"integer","title":"Order"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url"},"hidden":{"type":"boolean","title":"Hidden","description":"Hidden from the public help-center home (still reachable by link and search)."},"is_section":{"type":"boolean","title":"Is Section","description":"Shown inline on its parent's page as a heading with its articles."},"parent_group_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Group Id","description":"The parent collection's group_id; null at the top level."},"language":{"type":"string","title":"Language"},"translation":{"$ref":"#/components/schemas/Translation"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"article_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Article Count","description":"Articles directly in this collection, on list responses."},"children":{"items":{"$ref":"#/components/schemas/CollectionNode"},"type":"array","title":"Children"}},"additionalProperties":false,"type":"object","required":["id","group_id","name","slug","description","order","image_url","hidden","is_section","parent_group_id","language","translation","created_at","children"],"title":"CollectionNode","examples":[{"created_at":"2026-09-01T09:00:00+00:00","description":"Finding, filtering and exporting orders.","group_id":"cg81…","hidden":false,"id":"k3e2…","is_section":false,"language":"en","name":"Orders","order":0,"slug":"orders","translation":{"available_languages":["en"],"machine_translated":false,"stale":false}}]},"CollectionTree":{"properties":{"data":{"items":{"$ref":"#/components/schemas/CollectionNode"},"type":"array","title":"Data"},"language":{"type":"string","title":"Language"}},"additionalProperties":false,"type":"object","required":["data","language"],"title":"CollectionTree","examples":[{"data":[{"children":[],"created_at":"2026-09-01T09:00:00+00:00","description":"Finding, filtering and exporting orders.","group_id":"cg81…","hidden":false,"id":"k3e2…","is_section":false,"language":"en","name":"Orders","order":0,"slug":"orders","translation":{"available_languages":["en"],"machine_translated":false,"stale":false}}],"language":"en"}]},"CollectionUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"order":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Order"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url"},"hidden":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Hidden"},"is_section":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Section"},"parent_group_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Group Id"}},"type":"object","title":"CollectionUpdate","examples":[{"hidden":true}]},"Comment":{"properties":{"id":{"type":"string","title":"Id"},"article_group_id":{"type":"string","title":"Article Group Id"},"body":{"type":"string","title":"Body"},"kind":{"type":"string","title":"Kind","description":"`comment`, or a finding left by a quality review."},"status":{"type":"string","enum":["open","resolved"],"title":"Status"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"resolved_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Resolved At"}},"additionalProperties":false,"type":"object","required":["id","article_group_id","body","kind","status","created_at","resolved_at"],"title":"Comment","examples":[{"article_group_id":"g91c…","body":"Step 3 should mention the date filter.","created_at":"2026-10-01T12:00:00+00:00","id":"cm12…","kind":"comment","status":"open"}]},"CommentCreate":{"properties":{"body":{"type":"string","minLength":1,"title":"Body"}},"type":"object","required":["body"],"title":"CommentCreate","examples":[{"body":"Step 3 should mention the date filter."}]},"CommentList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Comment"},"type":"array","title":"Data"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"additionalProperties":false,"type":"object","required":["data","pagination"],"title":"CommentList","examples":[{"data":[{"article_group_id":"g91c…","body":"Step 3 should mention the date filter.","created_at":"2026-10-01T12:00:00+00:00","id":"cm12…","kind":"comment","status":"open"}],"pagination":{"has_more":false,"limit":25,"offset":0,"total":1}}]},"CommentUpdate":{"properties":{"body":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Body"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"`open` or `resolved`."}},"type":"object","title":"CommentUpdate","examples":[{"status":"resolved"}]},"Coverage":{"properties":{"data":{"additionalProperties":{"type":"string","enum":["done","running","queued","failed"]},"type":"object","title":"Data","description":"Article group_id → best walkthrough state."},"counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Counts"}},"additionalProperties":false,"type":"object","required":["data","counts"],"title":"Coverage","examples":[{"counts":{"done":1,"failed":0,"queued":1,"running":0},"data":{"g44a…":"queued","g91c…":"done"}}]},"EnqueueIn":{"properties":{"platform_id":{"type":"string","title":"Platform Id","description":"The connected platform to drive."},"group_ids":{"items":{"type":"string"},"type":"array","title":"Group Ids","description":"Article group_ids to generate walkthroughs for."},"all_missing":{"type":"boolean","title":"All Missing","description":"Instead of group_ids, target every AI draft that has no successful or in-flight walkthrough.","default":false},"screenshots_only":{"type":"boolean","title":"Screenshots Only","description":"Skip video capture.","default":true}},"type":"object","required":["platform_id"],"title":"EnqueueIn","examples":[{"group_ids":["g91c…"],"platform_id":"acme-app","screenshots_only":true}]},"Enqueued":{"properties":{"running":{"type":"integer","title":"Running"},"started":{"type":"integer","title":"Started"},"auth_blocked":{"items":{"type":"string"},"type":"array","title":"Auth Blocked","description":"Platforms whose saved login expired — their queue is paused."},"queued":{"type":"integer","title":"Queued"},"skipped_active":{"type":"integer","title":"Skipped Active","description":"Already queued or running — not duplicated."},"over_quota":{"type":"integer","title":"Over Quota","description":"Not queued: the plan's walkthrough runs for the period are used up."}},"additionalProperties":false,"type":"object","required":["running","started","auth_blocked","queued","skipped_active","over_quota"],"title":"Enqueued","examples":[{"auth_blocked":[],"over_quota":0,"queued":5,"running":2,"skipped_active":1,"started":2}]},"ErrorDetail":{"additionalProperties":false,"properties":{"type":{"description":"Stable machine-readable error type — branch on this, not on `message`.","title":"Type","type":"string"},"status":{"description":"The HTTP status code, repeated.","title":"Status","type":"integer"},"message":{"description":"Human-readable explanation; may be reworded.","title":"Message","type":"string"},"fields":{"anyOf":[{"items":{"$ref":"#/components/schemas/FieldError"},"type":"array"},{"type":"null"}],"default":null,"description":"Present on `invalid_request` (422).","title":"Fields"}},"required":["type","status","message"],"title":"ErrorDetail","type":"object"},"ErrorEnvelope":{"additionalProperties":false,"description":"Every ``/v1`` error has this shape.","examples":[{"error":{"message":"article not found","status":404,"type":"not_found"}}],"properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"title":"ErrorEnvelope","type":"object"},"FieldError":{"additionalProperties":false,"properties":{"field":{"description":"Dotted path of the offending field, e.g. `title`.","title":"Field","type":"string"},"reason":{"title":"Reason","type":"string"}},"required":["field","reason"],"title":"FieldError","type":"object"},"GlossaryTerm":{"properties":{"term":{"type":"string","title":"Term"},"definition":{"type":"string","title":"Definition"}},"type":"object","required":["term","definition"],"title":"GlossaryTerm"},"ItemSurface":{"properties":{"key":{"type":"string","title":"Key"},"match":{"type":"string","enum":["declared","located","inferred"],"title":"Match","description":"How the link was made, strongest first: `declared` — cited when the item was extracted; `located` — the item's location in the UI names this screen on its detail sheet; `inferred` — the item shares a meaningful word with a surface in its own part of the code."}},"additionalProperties":false,"type":"object","required":["key","match"],"title":"ItemSurface"},"JobStart":{"properties":{"kind":{"type":"string","title":"Kind","description":"One of: build, suggest, suggest_collections, suggest_reorg, quality_check, verify_repair, build_lexicon."},"public_only":{"type":"boolean","title":"Public Only","description":"Restrict the run to user-facing (non-internal) knowledge.","default":false}},"type":"object","required":["kind"],"title":"JobStart","examples":[{"kind":"build"}]},"KbItem":{"properties":{"key":{"type":"string","title":"Key","description":"Stable across rebuilds while the item keeps documenting the same thing."},"kind":{"type":"string","enum":["feature","use_case","term"],"title":"Kind"},"title":{"type":"string","title":"Title"},"summary":{"type":"string","title":"Summary"},"detail":{"type":"string","title":"Detail"},"location":{"type":"string","title":"Location","description":"Where it is found in the product."},"steps":{"items":{"type":"string"},"type":"array","title":"Steps","description":"For use cases: the steps, in order."},"audience":{"type":"string","title":"Audience"},"publishable":{"type":"boolean","title":"Publishable","description":"Suitable for the public help center."},"surfaces":{"items":{"$ref":"#/components/schemas/ItemSurface"},"type":"array","title":"Surfaces"},"version":{"type":"integer","title":"Version","description":"Knowledge-base version the item belongs to."},"sources":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Sources","description":"Source directories — only with the `source:read` scope."}},"additionalProperties":false,"type":"object","required":["key","kind","title","summary","detail","location","steps","audience","publishable","surfaces","version"],"title":"KbItem","examples":[{"audience":"user","detail":"","key":"feature/export-orders","kind":"feature","location":"Orders → Export","publishable":true,"steps":[],"summary":"Download any filtered order list as a CSV file.","surfaces":[{"key":"route:/orders","match":"declared"}],"title":"Export orders","version":7}]},"KbItemDetail":{"properties":{"key":{"type":"string","title":"Key","description":"Stable across rebuilds while the item keeps documenting the same thing."},"kind":{"type":"string","enum":["feature","use_case","term"],"title":"Kind"},"title":{"type":"string","title":"Title"},"summary":{"type":"string","title":"Summary"},"detail":{"type":"string","title":"Detail"},"location":{"type":"string","title":"Location","description":"Where it is found in the product."},"steps":{"items":{"type":"string"},"type":"array","title":"Steps","description":"For use cases: the steps, in order."},"audience":{"type":"string","title":"Audience"},"publishable":{"type":"boolean","title":"Publishable","description":"Suitable for the public help center."},"surfaces":{"items":{"$ref":"#/components/schemas/ItemSurface"},"type":"array","title":"Surfaces"},"version":{"type":"integer","title":"Version","description":"Knowledge-base version the item belongs to."},"sources":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Sources","description":"Source directories — only with the `source:read` scope."},"related":{"items":{"$ref":"#/components/schemas/RelatedItem"},"type":"array","title":"Related"},"surface_details":{"items":{"$ref":"#/components/schemas/Surface"},"type":"array","title":"Surface Details"}},"additionalProperties":false,"type":"object","required":["key","kind","title","summary","detail","location","steps","audience","publishable","surfaces","version","related","surface_details"],"title":"KbItemDetail","examples":[{"audience":"user","detail":"","key":"feature/export-orders","kind":"feature","location":"Orders → Export","publishable":true,"related":[{"key":"use_case/monthly-report","rel":"uses","title":"Send the monthly report"}],"steps":[],"summary":"Download any filtered order list as a CSV file.","surface_details":[{"framework":"nextjs","key":"route:/orders","kind":"route","label":"Orders","name":"/orders"}],"surfaces":[{"key":"route:/orders","match":"declared"}],"title":"Export orders","version":7}]},"KbItemHit":{"properties":{"key":{"type":"string","title":"Key","description":"Stable across rebuilds while the item keeps documenting the same thing."},"kind":{"type":"string","enum":["feature","use_case","term"],"title":"Kind"},"title":{"type":"string","title":"Title"},"summary":{"type":"string","title":"Summary"},"detail":{"type":"string","title":"Detail"},"location":{"type":"string","title":"Location","description":"Where it is found in the product."},"steps":{"items":{"type":"string"},"type":"array","title":"Steps","description":"For use cases: the steps, in order."},"audience":{"type":"string","title":"Audience"},"publishable":{"type":"boolean","title":"Publishable","description":"Suitable for the public help center."},"surfaces":{"items":{"$ref":"#/components/schemas/ItemSurface"},"type":"array","title":"Surfaces"},"version":{"type":"integer","title":"Version","description":"Knowledge-base version the item belongs to."},"sources":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Sources","description":"Source directories — only with the `source:read` scope."},"rank":{"type":"number","title":"Rank","description":"Relevance, 0–1; results are sorted by it."}},"additionalProperties":false,"type":"object","required":["key","kind","title","summary","detail","location","steps","audience","publishable","surfaces","version","rank"],"title":"KbItemHit","examples":[{"audience":"user","detail":"","key":"feature/export-orders","kind":"feature","location":"Orders → Export","publishable":true,"steps":[],"summary":"Download any filtered order list as a CSV file.","surfaces":[{"key":"route:/orders","match":"declared"}],"title":"Export orders","version":7}]},"KbItemList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/KbItem"},"type":"array","title":"Data"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"additionalProperties":false,"type":"object","required":["data","pagination"],"title":"KbItemList","examples":[{"data":[{"audience":"user","detail":"","key":"feature/export-orders","kind":"feature","location":"Orders → Export","publishable":true,"steps":[],"summary":"Download any filtered order list as a CSV file.","surfaces":[{"key":"route:/orders","match":"declared"}],"title":"Export orders","version":7}],"pagination":{"has_more":false,"limit":25,"offset":0,"total":1}}]},"KbItemSearch":{"properties":{"data":{"items":{"$ref":"#/components/schemas/KbItemHit"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"KbItemSearch","examples":[{"data":[{"audience":"user","detail":"","key":"feature/export-orders","kind":"feature","location":"Orders → Export","publishable":true,"rank":0.67,"steps":[],"summary":"Download any filtered order list as a CSV file.","surfaces":[{"key":"route:/orders","match":"declared"}],"title":"Export orders","version":7}]}]},"KbJob":{"properties":{"id":{"type":"string","title":"Id"},"kind":{"type":"string","title":"Kind","description":"`build`, `suggest`, …"},"status":{"type":"string","enum":["running","done","error","canceled"],"title":"Status"},"phase":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phase","description":"What it is doing now (`reading`, `mapping`, …), or `up_to_date` when a build had nothing to do."},"processed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Processed"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"},"created_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Created Count","description":"Suggestions created so far, for suggestion jobs."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Why it stopped, when `status` is `error` — names the AI credential refused, if any."},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"additionalProperties":false,"type":"object","required":["id","kind","status","phase","processed","total","created_count","error","created_at","updated_at"],"title":"KbJob","examples":[{"created_at":"2026-10-02T09:00:00+00:00","created_count":0,"id":"j77…","kind":"build","phase":"reading","processed":12,"status":"running","total":40,"updated_at":"2026-10-02T09:03:00+00:00"}]},"KbJobList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/KbJob"},"type":"array","title":"Data"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"additionalProperties":false,"type":"object","required":["data","pagination"],"title":"KbJobList","examples":[{"data":[{"created_at":"2026-10-02T09:00:00+00:00","created_count":0,"id":"j77…","kind":"build","phase":"reading","processed":12,"status":"running","total":40,"updated_at":"2026-10-02T09:03:00+00:00"}],"pagination":{"has_more":false,"limit":25,"offset":0,"total":1}}]},"KbProfile":{"properties":{"audience":{"type":"string","enum":["end_user","developer","data_practitioner"],"title":"Audience","default":"end_user"},"granularity":{"type":"string","enum":["consolidated","per_surface"],"title":"Granularity","default":"consolidated"}},"type":"object","title":"KbProfile","examples":[{"audience":"developer","granularity":"per_surface"}]},"KbStatus":{"properties":{"exists":{"type":"boolean","title":"Exists"},"version":{"type":"integer","title":"Version"},"generated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Generated At"},"counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Counts"}},"additionalProperties":false,"type":"object","required":["exists","version","counts"],"title":"KbStatus","examples":[{"counts":{"features":38,"glossary":54,"use_cases":21},"exists":true,"generated_at":"2026-10-01T16:00:00+00:00","version":7}]},"KeyInfo":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"prefix":{"type":"string","title":"Prefix","description":"The key's public prefix, e.g. `mp_live_a1b2c3d4` — safe to log."},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes","description":"Scopes as granted (may include wildcards)."},"effective_scopes":{"items":{"type":"string"},"type":"array","title":"Effective Scopes","description":"Scopes after expanding wildcards."},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At"},"request_count":{"type":"integer","title":"Request Count"}},"additionalProperties":false,"type":"object","required":["id","name","prefix","scopes","effective_scopes","expires_at","last_used_at","request_count"],"title":"KeyInfo"},"KnowledgeExport":{"properties":{"format":{"type":"string","const":"macroprimer.knowledge/v1","title":"Format"},"version":{"type":"integer","title":"Version"},"generated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Generated At"},"profile":{"$ref":"#/components/schemas/ProfileValue"},"overview_md":{"type":"string","title":"Overview Md"},"navigation_md":{"type":"string","title":"Navigation Md"},"items":{"items":{"$ref":"#/components/schemas/KbItem"},"type":"array","title":"Items"},"links":{"items":{"$ref":"#/components/schemas/Link"},"type":"array","title":"Links"},"surfaces":{"items":{"$ref":"#/components/schemas/Surface"},"type":"array","title":"Surfaces"}},"additionalProperties":false,"type":"object","required":["format","version","generated_at","profile","overview_md","navigation_md","items","links","surfaces"],"title":"KnowledgeExport","examples":[{"format":"macroprimer.knowledge/v1","generated_at":"2026-10-01T16:00:00+00:00","items":[{"audience":"user","detail":"","key":"feature/export-orders","kind":"feature","location":"Orders → Export","publishable":true,"steps":[],"summary":"Download any filtered order list as a CSV file.","surfaces":[{"key":"route:/orders","match":"declared"}],"title":"Export orders","version":7}],"links":[{"rel":"uses","source":"use_case/monthly-report","target":"feature/export-orders"}],"navigation_md":"- **Orders** …","overview_md":"Acme is an order-management app…","profile":{"audience":"end_user","granularity":"consolidated"},"surfaces":[{"documented_by":["feature/export-orders"],"framework":"nextjs","key":"route:/orders","kind":"route","label":"Orders","name":"/orders"}],"version":7}]},"LanguageOption":{"properties":{"code":{"type":"string","title":"Code"},"name":{"type":"string","title":"Name"}},"additionalProperties":false,"type":"object","required":["code","name"],"title":"LanguageOption"},"Languages":{"properties":{"default_language":{"type":"string","title":"Default Language"},"active_languages":{"items":{"type":"string"},"type":"array","title":"Active Languages"},"options":{"items":{"$ref":"#/components/schemas/LanguageOption"},"type":"array","title":"Options","description":"Every language the help center supports."}},"additionalProperties":false,"type":"object","required":["default_language","active_languages","options"],"title":"Languages","examples":[{"active_languages":["en","es"],"default_language":"en","options":[{"code":"en","name":"English"},{"code":"es","name":"Spanish"}]}]},"LanguagesSet":{"properties":{"default_language":{"type":"string","title":"Default Language"},"active_languages":{"items":{"type":"string"},"type":"array","title":"Active Languages"}},"additionalProperties":false,"type":"object","required":["default_language","active_languages"],"title":"LanguagesSet","examples":[{"active_languages":["en","es"],"default_language":"en"}]},"LanguagesUpdate":{"properties":{"default_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Language"},"active_languages":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Active Languages","description":"Languages the help center publishes. Must include the default."}},"type":"object","title":"LanguagesUpdate","examples":[{"active_languages":["en","es"],"default_language":"en"}]},"Link":{"properties":{"source":{"type":"string","title":"Source"},"target":{"type":"string","title":"Target"},"rel":{"type":"string","title":"Rel"}},"additionalProperties":false,"type":"object","required":["source","target","rel"],"title":"Link"},"MapData":{"properties":{"overview_md":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Overview Md"},"navigation_md":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Navigation Md"},"features":{"anyOf":[{"items":{"$ref":"#/components/schemas/MapFeature"},"type":"array"},{"type":"null"}],"title":"Features"},"use_cases":{"anyOf":[{"items":{"$ref":"#/components/schemas/MapUseCase"},"type":"array"},{"type":"null"}],"title":"Use Cases"},"glossary":{"anyOf":[{"items":{"$ref":"#/components/schemas/GlossaryTerm"},"type":"array"},{"type":"null"}],"title":"Glossary"}},"additionalProperties":false,"type":"object","title":"MapData"},"MapFeature":{"properties":{"key":{"type":"string","title":"Key"},"title":{"type":"string","title":"Title"},"summary":{"type":"string","title":"Summary"}},"type":"object","required":["key","title","summary"],"title":"MapFeature","description":"A product capability. Further fields may appear as the knowledge model grows."},"MapMeta":{"properties":{"version":{"type":"integer","title":"Version"},"built_from_sha":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Built From Sha"},"generated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Generated At"}},"additionalProperties":false,"type":"object","required":["version","built_from_sha","generated_at"],"title":"MapMeta"},"MapUseCase":{"properties":{"title":{"type":"string","title":"Title"},"summary":{"type":"string","title":"Summary"},"steps":{"items":{"type":"string"},"type":"array","title":"Steps","default":[]}},"type":"object","required":["title","summary"],"title":"MapUseCase","description":"A workflow people complete with the product. Further fields may appear."},"Me":{"properties":{"api_key":{"$ref":"#/components/schemas/KeyInfo"},"workspace":{"anyOf":[{"$ref":"#/components/schemas/WorkspaceRef"},{"type":"null"}]}},"additionalProperties":false,"type":"object","required":["api_key","workspace"],"title":"Me","examples":[{"api_key":{"effective_scopes":["articles:read","articles:write"],"expires_at":"2026-11-17T00:00:00+00:00","id":"3f1c…","last_used_at":"2026-10-02T14:03:11+00:00","name":"CI publishing","prefix":"mp_live_a1b2c3d4","request_count":1043,"scopes":["articles:read","articles:write"]},"workspace":{"id":"c1a2…","name":"Acme","slug":"acme"}}]},"Overview":{"properties":{"exists":{"type":"boolean","title":"Exists"},"version":{"type":"integer","title":"Version"},"profile":{"$ref":"#/components/schemas/ProfileValue"},"overview_md":{"type":"string","title":"Overview Md"},"navigation_md":{"type":"string","title":"Navigation Md"},"items":{"additionalProperties":{"type":"integer"},"type":"object","title":"Items","description":"Item counts by kind."},"surfaces":{"additionalProperties":{"type":"integer"},"type":"object","title":"Surfaces","description":"Surface counts by kind."}},"additionalProperties":false,"type":"object","required":["exists","version","profile","overview_md","navigation_md","items","surfaces"],"title":"Overview","examples":[{"exists":true,"items":{"feature":38,"term":54,"use_case":21},"navigation_md":"- **Orders** …","overview_md":"Acme is an order-management app…","profile":{"audience":"end_user","granularity":"consolidated"},"surfaces":{"route":64,"screen":30},"version":7}]},"Pagination":{"properties":{"limit":{"type":"integer","title":"Limit","description":"Items per page, as requested (1–100)."},"offset":{"type":"integer","title":"Offset","description":"Items skipped, as requested."},"total":{"type":"integer","title":"Total","description":"Items matching the filters, across all pages."},"has_more":{"type":"boolean","title":"Has More","description":"True while another page follows; page until false."}},"additionalProperties":false,"type":"object","required":["limit","offset","total","has_more"],"title":"Pagination"},"Plan":{"properties":{"name":{"type":"string","title":"Name"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"current_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Current Period End"},"limits":{"$ref":"#/components/schemas/PlanLimits"}},"additionalProperties":false,"type":"object","required":["name","status","current_period_end","limits"],"title":"Plan"},"PlanLimits":{"properties":{"articles":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Articles","description":"Max published articles; null = unlimited."},"seats":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Seats"},"walkthroughs":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Walkthroughs","description":"Walkthrough runs per billing period; null = unlimited."},"ai_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ai Usd","description":"Dollars of AI included per calendar month (UTC); null = no workspace cap."},"languages":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Languages"},"requests_per_minute":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Requests Per Minute","description":"This API's rate limit for the workspace."},"intercom_import":{"type":"boolean","title":"Intercom Import"},"custom_domain":{"type":"boolean","title":"Custom Domain"},"remove_branding":{"type":"boolean","title":"Remove Branding"}},"additionalProperties":false,"type":"object","required":["articles","seats","walkthroughs","ai_usd","languages","requests_per_minute","intercom_import","custom_domain","remove_branding"],"title":"PlanLimits"},"ProductMap":{"properties":{"exists":{"type":"boolean","title":"Exists","description":"False (with 200) when no knowledge base has been built yet."},"data":{"anyOf":[{"$ref":"#/components/schemas/MapData"},{"type":"null"}]},"meta":{"anyOf":[{"$ref":"#/components/schemas/MapMeta"},{"type":"null"}]}},"additionalProperties":false,"type":"object","required":["exists","data"],"title":"ProductMap","examples":[{"data":{"features":[{"key":"export-orders","summary":"Download orders as CSV.","title":"Export orders"}],"glossary":[],"overview_md":"Acme is an order-management app…","use_cases":[]},"exists":true,"meta":{"generated_at":"2026-10-01T16:00:00+00:00","version":7}}]},"ProductProfile":{"properties":{"profile":{"$ref":"#/components/schemas/ProfileValue"},"is_set":{"type":"boolean","title":"Is Set","description":"False when the default profile applies because none was chosen."},"suggestion":{"$ref":"#/components/schemas/ProfileSuggestion"}},"additionalProperties":false,"type":"object","required":["profile","is_set","suggestion"],"title":"ProductProfile","examples":[{"is_set":true,"profile":{"audience":"developer","granularity":"per_surface"},"suggestion":{"confident":true,"signals":["a command-line entry point in pyproject.toml"],"suggested":{"audience":"developer","granularity":"consolidated"}}}]},"ProfileSuggestion":{"properties":{"suggested":{"$ref":"#/components/schemas/ProfileValue"},"signals":{"items":{"type":"string"},"type":"array","title":"Signals","description":"What in the code led to the suggestion."},"confident":{"type":"boolean","title":"Confident"}},"additionalProperties":false,"type":"object","required":["suggested","signals","confident"],"title":"ProfileSuggestion"},"ProfileValue":{"properties":{"audience":{"type":"string","enum":["end_user","developer","data_practitioner"],"title":"Audience"},"granularity":{"type":"string","enum":["consolidated","per_surface"],"title":"Granularity"}},"additionalProperties":false,"type":"object","required":["audience","granularity"],"title":"ProfileValue"},"Quality":{"properties":{"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score","description":"0–100 grounding score from the last quality review; null if never reviewed."},"flags":{"items":{},"type":"array","title":"Flags","description":"Findings from the last quality review."},"checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Checked At"}},"additionalProperties":false,"type":"object","required":["score","flags","checked_at"],"title":"Quality"},"QueueState":{"properties":{"running":{"type":"integer","title":"Running"},"started":{"type":"integer","title":"Started"},"auth_blocked":{"items":{"type":"string"},"type":"array","title":"Auth Blocked","description":"Platforms whose saved login expired — their queue is paused."}},"additionalProperties":false,"type":"object","required":["running","started","auth_blocked"],"title":"QueueState","examples":[{"auth_blocked":[],"running":2,"started":1}]},"RelatedItem":{"properties":{"key":{"type":"string","title":"Key"},"title":{"type":"string","title":"Title"},"rel":{"type":"string","title":"Rel","description":"How the two items relate, e.g. `uses`, `part_of`, `see_also`."}},"additionalProperties":false,"type":"object","required":["key","title","rel"],"title":"RelatedItem"},"ReorderIn":{"properties":{"group_ids":{"items":{"type":"string"},"type":"array","title":"Group Ids","description":"Sibling collection group_ids, in the order you want them displayed."}},"type":"object","required":["group_ids"],"title":"ReorderIn","examples":[{"group_ids":["cg81…","cg12…","cg55…"]}]},"Reordered":{"properties":{"ok":{"type":"boolean","title":"Ok"},"reordered":{"type":"integer","title":"Reordered"}},"additionalProperties":false,"type":"object","required":["ok","reordered"],"title":"Reordered","examples":[{"ok":true,"reordered":3}]},"RetryIn":{"properties":{"group_id":{"type":"string","title":"Group Id"},"platform_id":{"type":"string","title":"Platform Id"},"screenshots_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Screenshots Only","description":"Omit to keep the mode of the article's last run."}},"type":"object","required":["group_id","platform_id"],"title":"RetryIn","examples":[{"group_id":"g91c…","platform_id":"acme-app"}]},"Revision":{"properties":{"id":{"type":"string","title":"Id"},"rev_num":{"type":"integer","title":"Rev Num"},"source":{"type":"string","title":"Source"},"title":{"type":"string","title":"Title"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Excerpt"},"body":{"type":"string","title":"Body"},"status":{"type":"string","title":"Status"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"}},"additionalProperties":false,"type":"object","required":["id","rev_num","source","title","excerpt","body","status","language","created_at"],"title":"Revision","examples":[{"body":"<p>Open <strong>Orders</strong>…</p>","created_at":"2026-10-01T16:40:00+00:00","excerpt":"Download any filtered order list as a spreadsheet.","id":"r55…","language":"en","rev_num":3,"source":"edit","status":"published","title":"Export orders to CSV"}]},"RevisionList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/RevisionSummary"},"type":"array","title":"Data"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"additionalProperties":false,"type":"object","required":["data","pagination"],"title":"RevisionList","examples":[{"data":[{"bytes":1840,"created_at":"2026-10-01T16:40:00+00:00","id":"r55…","is_current":true,"rev_num":3,"source":"edit","status":"published","title":"Export orders to CSV"}],"pagination":{"has_more":false,"limit":25,"offset":0,"total":3}}]},"RevisionSummary":{"properties":{"id":{"type":"string","title":"Id"},"rev_num":{"type":"integer","title":"Rev Num"},"source":{"type":"string","title":"Source","description":"What produced it: `edit`, `revert`, `translate`, `import`, …"},"title":{"type":"string","title":"Title"},"status":{"type":"string","title":"Status"},"bytes":{"type":"integer","title":"Bytes","description":"Body size, so a client can spot large edits without fetching them."},"is_current":{"type":"boolean","title":"Is Current"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"}},"additionalProperties":false,"type":"object","required":["id","rev_num","source","title","status","bytes","is_current","created_at"],"title":"RevisionSummary"},"ScopeInfo":{"properties":{"scope":{"type":"string","title":"Scope"},"resource":{"type":"string","title":"Resource"},"action":{"type":"string","title":"Action"},"description":{"type":"string","title":"Description"},"granted":{"type":"boolean","title":"Granted","description":"Whether the calling key holds this scope."}},"additionalProperties":false,"type":"object","required":["scope","resource","action","description","granted"],"title":"ScopeInfo"},"ScopeList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ScopeInfo"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"ScopeList","examples":[{"data":[{"action":"read","description":"Read articles, bodies and revision history.","granted":true,"resource":"articles","scope":"articles:read"}]}]},"SearchHit":{"properties":{"type":{"type":"string","enum":["article","collection"],"title":"Type"},"id":{"type":"string","title":"Id"},"group_id":{"type":"string","title":"Group Id"},"title":{"type":"string","title":"Title"},"slug":{"type":"string","title":"Slug"},"snippet":{"type":"string","title":"Snippet"},"rank":{"type":"integer","title":"Rank","description":"Higher is better: a title match outranks a body match."},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Articles only."},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id","description":"Articles only."},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"Articles only."}},"additionalProperties":false,"type":"object","required":["type","id","group_id","title","slug","snippet","rank"],"title":"SearchHit"},"SearchResults":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SearchHit"},"type":"array","title":"Data"},"query":{"type":"string","title":"Query"},"language":{"type":"string","title":"Language"},"count":{"type":"integer","title":"Count"}},"additionalProperties":false,"type":"object","required":["data","query","language","count"],"title":"SearchResults","examples":[{"count":1,"data":[{"collection_id":"k3e2…","group_id":"g91c…","id":"a7d4…","rank":3,"slug":"export-orders-to-csv","snippet":"…filter the list, then choose Export…","status":"published","title":"Export orders to CSV","type":"article","updated_at":"2026-10-01T16:40:00+00:00"}],"language":"en","query":"export"}]},"SessionAi":{"properties":{"provider":{"type":"string","title":"Provider"},"base_url":{"type":"string","title":"Base Url"},"models":{"$ref":"#/components/schemas/SessionModels","description":"The models a run's token is limited to."}},"additionalProperties":false,"type":"object","required":["provider","base_url","models"],"title":"SessionAi"},"SessionBudget":{"properties":{"monthly_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Monthly Usd","description":"Model use MacroPrimer covers per calendar month (UTC); null = no workspace cap."},"remaining_usd":{"type":"number","title":"Remaining Usd"}},"additionalProperties":false,"type":"object","required":["monthly_usd","remaining_usd"],"title":"SessionBudget"},"SessionIn":{"properties":{"repo":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$","title":"Repo"},"sha":{"type":"string","maxLength":64,"title":"Sha"}},"additionalProperties":false,"type":"object","required":["repo","sha"],"title":"SessionIn","examples":[{"repo":"acme/shop","sha":"9f2c4e1"}]},"SessionModels":{"properties":{"main":{"type":"string","title":"Main"},"fast":{"type":"string","title":"Fast"}},"additionalProperties":false,"type":"object","required":["main","fast"],"title":"SessionModels"},"SessionProfile":{"properties":{"audience":{"type":"string","title":"Audience"},"granularity":{"type":"string","title":"Granularity"},"surface_kinds":{"items":{"type":"string"},"type":"array","title":"Surface Kinds"}},"additionalProperties":false,"type":"object","required":["audience","granularity","surface_kinds"],"title":"SessionProfile"},"SheetAction":{"properties":{"label":{"type":"string","title":"Label","description":"Button, menu item or link text, as shown."},"trigger":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trigger","description":"How it is invoked."},"effect":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Effect","description":"What happens, including messages shown afterwards."},"confirmation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Confirmation","description":"Confirmation prompt text, if any."},"visible_when":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Visible When"},"permission":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Permission"}},"additionalProperties":false,"type":"object","required":["label"],"title":"SheetAction"},"SheetColumn":{"properties":{"name":{"type":"string","title":"Name"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"additionalProperties":false,"type":"object","required":["name"],"title":"SheetColumn"},"SheetField":{"properties":{"label":{"type":"string","title":"Label","description":"As shown to the user."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"required":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Required"},"validation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Validation"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"additionalProperties":false,"type":"object","required":["label"],"title":"SheetField"},"SheetParameter":{"properties":{"name":{"type":"string","title":"Name"},"in":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"In","description":"`path`, `query`, `header` or `body`."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"required":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Required"},"default":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"additionalProperties":false,"type":"object","required":["name"],"title":"SheetParameter"},"SheetResponse":{"properties":{"status":{"type":"string","title":"Status","description":"HTTP status code."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"additionalProperties":false,"type":"object","required":["status"],"title":"SheetResponse"},"Stats":{"properties":{"published_articles":{"type":"integer","title":"Published Articles"},"draft_articles":{"type":"integer","title":"Draft Articles"},"collections":{"type":"integer","title":"Collections"},"language":{"type":"string","title":"Language"},"walkthrough_runs_used":{"type":"integer","title":"Walkthrough Runs Used"}},"additionalProperties":false,"type":"object","required":["published_articles","draft_articles","collections","language","walkthrough_runs_used"],"title":"Stats","examples":[{"collections":9,"draft_articles":7,"language":"en","published_articles":42,"walkthrough_runs_used":3}]},"Suggestion":{"properties":{"id":{"type":"string","title":"Id"},"kind":{"type":"string","title":"Kind","description":"`new` (a new article) or `update` (a change to an existing one)."},"status":{"type":"string","title":"Status","description":"`pending`, `accepted` or `dismissed`."},"title":{"type":"string","title":"Title"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Excerpt"},"rationale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rationale"},"target_article_group_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Article Group Id","description":"The article an `update` suggestion changes."},"collection_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Name"},"citations":{"items":{},"type":"array","title":"Citations"},"quality":{"$ref":"#/components/schemas/SuggestionQuality"},"kb_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Kb Version","description":"Knowledge-base version it was drafted from."},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"body":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body","description":"Draft HTML, on single-suggestion responses or with `include_body=true`."}},"additionalProperties":false,"type":"object","required":["id","kind","status","title","excerpt","rationale","target_article_group_id","collection_name","citations","quality","kb_version","created_at"],"title":"Suggestion","examples":[{"body":"<p>Open <strong>Orders</strong>…</p>","citations":[],"collection_name":"Orders","created_at":"2026-10-02T09:10:00+00:00","excerpt":"Download any filtered order list as a spreadsheet.","id":"s31…","kb_version":7,"kind":"new","quality":{"flags":[],"score":88},"rationale":"Exporting is a documented feature with no article.","status":"pending","title":"Export orders to CSV"}]},"SuggestionList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Suggestion"},"type":"array","title":"Data"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"additionalProperties":false,"type":"object","required":["data","pagination"],"title":"SuggestionList","examples":[{"data":[{"citations":[],"collection_name":"Orders","created_at":"2026-10-02T09:10:00+00:00","excerpt":"Download any filtered order list as a spreadsheet.","id":"s31…","kb_version":7,"kind":"new","quality":{"flags":[],"score":88},"rationale":"Exporting is a documented feature with no article.","status":"pending","title":"Export orders to CSV"}],"pagination":{"has_more":false,"limit":25,"offset":0,"total":1}}]},"SuggestionQuality":{"properties":{"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score"},"flags":{"items":{},"type":"array","title":"Flags"},"verified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Verified At"}},"additionalProperties":false,"type":"object","required":["score","flags","verified_at"],"title":"SuggestionQuality"},"Surface":{"properties":{"key":{"type":"string","title":"Key","description":"Stable id, e.g. `route:/orders` or `endpoint:GET /v2/orders`."},"kind":{"type":"string","title":"Kind","description":"`screen`, `route`, `endpoint`, `command`, `symbol`, `pipeline`, `notebook`, `table`."},"name":{"type":"string","title":"Name"},"label":{"type":"string","title":"Label"},"framework":{"type":"string","title":"Framework"},"documented_by":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Documented By","description":"Keys of the items documenting it."},"file":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File","description":"Repository path — only with the `source:read` scope."},"target":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target","description":"File a route renders — only with `source:read`."},"sheet":{"anyOf":[{"$ref":"#/components/schemas/SurfaceSheet"},{"type":"null"}],"description":"Its detail sheet, when the knowledge base has written one (item details, single surfaces and exports; not lists)."}},"additionalProperties":false,"type":"object","required":["key","kind","name","label","framework"],"title":"Surface"},"SurfaceDetail":{"properties":{"key":{"type":"string","title":"Key","description":"Stable id, e.g. `route:/orders` or `endpoint:GET /v2/orders`."},"kind":{"type":"string","title":"Kind","description":"`screen`, `route`, `endpoint`, `command`, `symbol`, `pipeline`, `notebook`, `table`."},"name":{"type":"string","title":"Name"},"label":{"type":"string","title":"Label"},"framework":{"type":"string","title":"Framework"},"documented_by":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Documented By","description":"Keys of the items documenting it."},"file":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File","description":"Repository path — only with the `source:read` scope."},"target":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target","description":"File a route renders — only with `source:read`."},"sheet":{"anyOf":[{"$ref":"#/components/schemas/SurfaceSheet"},{"type":"null"}],"description":"Its detail sheet, when the knowledge base has written one (item details, single surfaces and exports; not lists)."}},"additionalProperties":false,"type":"object","required":["key","kind","name","label","framework"],"title":"SurfaceDetail","examples":[{"documented_by":["feature/export-orders"],"framework":"nextjs","key":"screen:/orders","kind":"screen","label":"Orders","name":"/orders","sheet":{"navigation":["Sidebar → Orders"],"purpose":"Browse past orders and refund them."}}]},"SurfaceList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Surface"},"type":"array","title":"Data"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"additionalProperties":false,"type":"object","required":["data","pagination"],"title":"SurfaceList","examples":[{"data":[{"documented_by":["feature/export-orders"],"framework":"nextjs","key":"route:/orders","kind":"route","label":"Orders","name":"/orders"}],"pagination":{"has_more":false,"limit":25,"offset":0,"total":1}}]},"SurfaceSheet":{"properties":{"purpose":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Purpose"},"navigation":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Navigation","description":"Screens: how to get there."},"layout":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Layout","description":"Screens: regions, top to bottom."},"fields":{"anyOf":[{"items":{"$ref":"#/components/schemas/SheetField"},"type":"array"},{"type":"null"}],"title":"Fields","description":"Screens: inputs the user fills in."},"actions":{"anyOf":[{"items":{"$ref":"#/components/schemas/SheetAction"},"type":"array"},{"type":"null"}],"title":"Actions","description":"Screens: buttons, menu items, links."},"states":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"States","description":"Loading, empty, error… with the text shown."},"permissions":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Permissions"},"prerequisites":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Prerequisites"},"related":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Related"},"keywords":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Keywords","description":"Words a user might search with."},"parameters":{"anyOf":[{"items":{"$ref":"#/components/schemas/SheetParameter"},"type":"array"},{"type":"null"}],"title":"Parameters","description":"Endpoints and symbols."},"responses":{"anyOf":[{"items":{"$ref":"#/components/schemas/SheetResponse"},"type":"array"},{"type":"null"}],"title":"Responses","description":"Endpoints: statuses returned."},"side_effects":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Side Effects"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage","description":"Commands: invocation."},"options":{"anyOf":[{"items":{"$ref":"#/components/schemas/SheetParameter"},"type":"array"},{"type":"null"}],"title":"Options","description":"Commands: options and flags."},"examples":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Examples"},"signature":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signature","description":"Symbols."},"returns":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Returns"},"raises":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Raises"},"inputs":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Inputs","description":"Pipelines, notebooks, tables."},"outputs":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Outputs"},"schedule":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule"},"columns":{"anyOf":[{"items":{"$ref":"#/components/schemas/SheetColumn"},"type":"array"},{"type":"null"}],"title":"Columns"}},"additionalProperties":false,"type":"object","title":"SurfaceSheet","description":"What one surface looks like and does, written from its code. Which sections\nappear depends on the surface's kind; empty ones are left out.","examples":[{"actions":[{"confirmation":"Refund this order?","effect":"Returns the money; shows “Order refunded”.","label":"Refund"}],"layout":["Orders table — columns: Date, Customer, Total"],"navigation":["Sidebar → Orders"],"permissions":["Only administrators can refund."],"purpose":"Browse past orders and refund them.","states":["empty: No orders yet"]}]},"TokenIn":{"properties":{"repo":{"type":"string","maxLength":200,"pattern":"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$","title":"Repo"},"sha":{"type":"string","maxLength":64,"title":"Sha"},"input_tokens":{"type":"integer","maximum":10000000000.0,"minimum":0.0,"title":"Input Tokens","description":"Upper bound of the run's model input."},"output_tokens":{"type":"integer","maximum":1000000000.0,"minimum":0.0,"title":"Output Tokens","description":"Upper bound of the run's model output."}},"additionalProperties":false,"type":"object","required":["repo","sha","input_tokens","output_tokens"],"title":"TokenIn","examples":[{"input_tokens":840000,"output_tokens":96000,"repo":"acme/shop","sha":"9f2c4e1"}]},"TranslateIn":{"properties":{"target_langs":{"items":{"type":"string"},"type":"array","title":"Target Langs","description":"Target language codes. Must be active on the workspace; the source language is ignored if listed."},"overwrite":{"type":"boolean","title":"Overwrite","description":"Re-translate variants that already exist and are not stale.","default":false}},"type":"object","title":"TranslateIn","examples":[{"overwrite":false,"target_langs":["es","fr"]}]},"TranslatedLanguage":{"properties":{"language":{"type":"string","title":"Language"},"status":{"type":"string","enum":["created","updated","skipped"],"title":"Status"},"article_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Article Id","description":"Article translations: the variant written."},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id","description":"Collection translations: the variant written."}},"additionalProperties":false,"type":"object","required":["language","status"],"title":"TranslatedLanguage"},"Translation":{"properties":{"source_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Language","description":"Language this variant was translated from."},"machine_translated":{"type":"boolean","title":"Machine Translated"},"stale":{"type":"boolean","title":"Stale","description":"The source changed after this variant was translated."},"available_languages":{"items":{"type":"string"},"type":"array","title":"Available Languages","description":"Languages this logical article/collection exists in."}},"additionalProperties":false,"type":"object","required":["machine_translated","stale","available_languages"],"title":"Translation"},"TranslationResult":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TranslatedLanguage"},"type":"array","title":"Data"},"source_language":{"type":"string","title":"Source Language"},"group_id":{"type":"string","title":"Group Id"}},"additionalProperties":false,"type":"object","required":["data","source_language","group_id"],"title":"TranslationResult","examples":[{"data":[{"article_id":"a8e1…","language":"es","status":"created"},{"language":"fr","status":"skipped"}],"group_id":"g91c…","source_language":"en"}]},"TranslationStatus":{"properties":{"available":{"type":"boolean","title":"Available","description":"Whether the workspace has an AI provider configured for translation."},"default_language":{"type":"string","title":"Default Language"},"active_languages":{"items":{"type":"string"},"type":"array","title":"Active Languages"}},"additionalProperties":false,"type":"object","required":["available","default_language","active_languages"],"title":"TranslationStatus","examples":[{"active_languages":["en","es","fr"],"available":true,"default_language":"en"}]},"UndocumentedSurface":{"properties":{"key":{"type":"string","title":"Key"},"kind":{"type":"string","title":"Kind"}},"additionalProperties":false,"type":"object","required":["key","kind"],"title":"UndocumentedSurface"},"WalkthroughJob":{"properties":{"id":{"type":"string","title":"Id"},"article_group_id":{"type":"string","title":"Article Group Id"},"platform_id":{"type":"string","title":"Platform Id"},"status":{"type":"string","enum":["queued","running","done","failed"],"title":"Status"},"screenshots_only":{"type":"boolean","title":"Screenshots Only"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"attempts":{"type":"integer","title":"Attempts"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"additionalProperties":false,"type":"object","required":["id","article_group_id","platform_id","status","screenshots_only","run_id","attempts","error","created_at","updated_at"],"title":"WalkthroughJob","examples":[{"article_group_id":"g91c…","attempts":1,"created_at":"2026-10-02T09:00:00+00:00","id":"w21…","platform_id":"acme-app","run_id":"20261002-0901-ab12","screenshots_only":true,"status":"done","updated_at":"2026-10-02T09:06:00+00:00"}]},"WalkthroughJobList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/WalkthroughJob"},"type":"array","title":"Data"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"additionalProperties":false,"type":"object","required":["data","pagination"],"title":"WalkthroughJobList","examples":[{"data":[{"article_group_id":"g91c…","attempts":1,"created_at":"2026-10-02T09:00:00+00:00","id":"w21…","platform_id":"acme-app","run_id":"20261002-0901-ab12","screenshots_only":true,"status":"done","updated_at":"2026-10-02T09:06:00+00:00"}],"pagination":{"has_more":false,"limit":25,"offset":0,"total":1}}]},"Workspace":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug","description":"The handle in `{slug}.help.macroprimer.com`."},"custom_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Custom Domain"},"help_center_url":{"type":"string","title":"Help Center Url"},"default_language":{"type":"string","title":"Default Language"},"active_languages":{"items":{"type":"string"},"type":"array","title":"Active Languages"},"plan":{"$ref":"#/components/schemas/Plan"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"}},"additionalProperties":false,"type":"object","required":["id","name","slug","custom_domain","help_center_url","default_language","active_languages","plan","created_at"],"title":"Workspace","examples":[{"active_languages":["en","es"],"created_at":"2026-06-01T00:00:00+00:00","custom_domain":"help.acme.com","default_language":"en","help_center_url":"https://help.acme.com","id":"c1a2…","name":"Acme","plan":{"current_period_end":"2026-11-01T00:00:00+00:00","limits":{"articles":150,"custom_domain":false,"intercom_import":true,"languages":3,"remove_branding":true,"requests_per_minute":300,"seats":5,"walkthroughs":25},"name":"pro","status":"active"},"slug":"acme"}]},"WorkspaceRef":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"}},"additionalProperties":false,"type":"object","required":["id","name","slug"],"title":"WorkspaceRef"},"WorkspaceUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Name"},"custom_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Custom Domain","description":"Bare hostname, e.g. help.yourcompany.com. Empty string clears it."}},"type":"object","title":"WorkspaceUpdate","examples":[{"custom_domain":"help.acme.com","name":"Acme Help"}]}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"mp_live_…","description":"A workspace API key from Settings → API keys."}}},"tags":[{"name":"meta","description":"Introspect the calling key and discover scopes."},{"name":"articles","description":"Help-center articles, their bodies and version history."},{"name":"collections","description":"The collection tree that organizes articles."},{"name":"comments","description":"Editorial comments and quality findings on articles."},{"name":"search","description":"Search across articles and collections."},{"name":"translations","description":"Machine-translate content into the workspace's active languages."},{"name":"knowledge","description":"The product map derived from connected repositories, and the jobs that build it."},{"name":"walkthroughs","description":"AI-generated product walkthroughs: enqueue, poll, coverage."},{"name":"assets","description":"The media library backing article content."},{"name":"workspace","description":"Settings, branding, languages, plan and statistics."}],"security":[{"apiKey":[]}]}