{"openapi":"3.1.0","info":{"title":"usedocs Docs API","version":"1.0.0","description":"Keep your help center in step with your code from your own tools and CI: read and edit articles, review what usedocs proposes, publish, and send code changes so usedocs drafts the doc edits.\n\n**Auth.** Send a workspace API key as `Authorization: Bearer ud_live_…`. Create keys in Settings → API and MCP. A `content:read` key can read; a `content:write` key can also change things. AI clients (Claude, Cursor, ChatGPT) connect to the MCP server with OAuth instead: Integrations → AI clients.\n\n**Bots.** A key covers one bot (help center) or every bot in the workspace. A workspace-wide key names the bot with `?bot_id=` or the `Usedocs-Bot` header when there's more than one.\n\n**Pages.** Lists take `page_size` (1 to 100, default 20) and `start_cursor`, and return `{results, has_more, next_cursor}`.\n\n**Errors.** `{error, code}` with an HTTP status. Rate limits: 120 requests a minute per key, and 30 tasks an hour; a 429 has `Retry-After`.\n\n**Tasks only propose.** A task (write an article, or document a code change) ends in drafts for review. Nothing goes live until someone applies or publishes it."},"servers":[{"url":"https://usedocs.app/v1"}],"security":[{"bearer":[]}],"tags":[{"name":"Articles","description":"Help center articles."},{"name":"Drafts","description":"Everything waiting for review: proposed edits to articles (edit_…), new articles written by usedocs (article_…), and drafts from customer questions (gap_…)."},{"name":"Revisions","description":"An article's earlier versions."},{"name":"Collections","description":"Groups of articles."},{"name":"Changelog","description":"Product updates."},{"name":"Tasks","description":"Background work that proposes changes: write an article, or update the docs for a code change."},{"name":"Insights","description":"Unanswered questions and doc health."},{"name":"Webhooks","description":"Signed events sent to your endpoint."},{"name":"Bots","description":"The help centers a key can manage."}],"paths":{"/bots":{"get":{"operationId":"listBots","tags":["Bots"],"summary":"List bots","description":"The bots (help centers) this key can manage.\n\n```bash\ncurl \"https://usedocs.app/v1/bots\" \\\n  -H \"Authorization: Bearer $USEDOCS_API_KEY\"\n```","responses":{"200":{"description":"The bots.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/articles":{"get":{"operationId":"listArticles","tags":["Articles"],"summary":"List articles","description":"Articles, newest change first.\n\n```bash\ncurl \"https://usedocs.app/v1/articles?status=published&page_size=50\" \\\n  -H \"Authorization: Bearer $USEDOCS_API_KEY\"\n```","security":[{"bearer":["content:read"]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["all","draft","in_review","published","archived"]}},{"name":"collection_id","in":"query","schema":{"type":"string"}},{"name":"locale","in":"query","schema":{"type":"string"}},{"name":"updated_since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only articles changed since then (incremental sync)."},{"name":"format","in":"query","schema":{"type":"string","enum":["markdown","html"],"default":"markdown"},"description":"contentMarkdown (default) or contentHtml."},{"name":"start_cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page."},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"One page of articles.","content":{"application/json":{"schema":{"type":"object","required":["results","has_more","next_cursor"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Article"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as start_cursor for the next page; null on the last page."}}}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createArticle","tags":["Articles"],"summary":"Create an article","description":"Creates a draft. Publish it with POST /articles/{id}/publish.\n\n```bash\ncurl -X POST \"https://usedocs.app/v1/articles\" \\\n  -H \"Authorization: Bearer $USEDOCS_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"title\":\"Export invoices to CSV\",\"contentMarkdown\":\"Open **Invoices**, then **Export**.\"}'\n```","security":[{"bearer":["content:write"]}],"parameters":[{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":200},"contentMarkdown":{"type":"string","description":"The article in Markdown."},"slug":{"type":"string"},"description":{"type":"string","description":"One sentence for search results and the article's lead."},"collectionId":{"type":["string","null"]},"visibility":{"type":"string","enum":["public","authenticated"]},"locale":{"type":"string","description":"Language code, e.g. en. Create only."},"position":{"type":"integer","description":"Order within its collection in the sidebar (0 first)."}},"required":["title","contentMarkdown"]}}}},"responses":{"201":{"description":"The new draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/articles/search":{"get":{"operationId":"searchArticles","tags":["Articles"],"summary":"Search articles","description":"Live articles that match a query, best match first.\n\n```bash\ncurl \"https://usedocs.app/v1/articles/search?q=export%20csv\" \\\n  -H \"Authorization: Bearer $USEDOCS_API_KEY\"\n```","security":[{"bearer":["content:read"]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2}},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"Matching articles.","content":{"application/json":{"schema":{"type":"object","required":["results","has_more","next_cursor"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Article"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as start_cursor for the next page; null on the last page."}}}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/articles/{id}":{"get":{"operationId":"getArticle","tags":["Articles"],"summary":"Get an article","description":"By id or slug.\n\n```bash\ncurl \"https://usedocs.app/v1/articles/export-invoices?format=markdown\" \\\n  -H \"Authorization: Bearer $USEDOCS_API_KEY\"\n```","security":[{"bearer":["content:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Article id or slug."},{"name":"format","in":"query","schema":{"type":"string","enum":["markdown","html"],"default":"markdown"},"description":"contentMarkdown (default) or contentHtml."},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"The article.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateArticle","tags":["Articles"],"summary":"Update an article","description":"Changes the article directly. On a live article the new text is live at once; to propose a change for review instead, use POST /articles/{id}/drafts. Status changes go through /publish and /unpublish.\n\n```bash\ncurl -X PATCH \"https://usedocs.app/v1/articles/export-invoices\" \\\n  -H \"Authorization: Bearer $USEDOCS_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"contentMarkdown\":\"Open **Invoices** → **Export** → **CSV**.\"}'\n```","security":[{"bearer":["content:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Article id or slug."},{"name":"format","in":"query","schema":{"type":"string","enum":["markdown","html"],"default":"markdown"},"description":"contentMarkdown (default) or contentHtml."},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":200},"contentMarkdown":{"type":"string","description":"The article in Markdown."},"slug":{"type":"string"},"description":{"type":"string","description":"One sentence for search results and the article's lead."},"collectionId":{"type":["string","null"]},"visibility":{"type":"string","enum":["public","authenticated"]},"locale":{"type":"string","description":"Language code, e.g. en. Create only."},"position":{"type":"integer","description":"Order within its collection in the sidebar (0 first)."}}}}}},"responses":{"200":{"description":"The updated article.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"trashArticle","tags":["Articles"],"summary":"Delete an article","description":"Moves it (and its translations) to Recently deleted. POST /articles/{id}/restore brings it back.","security":[{"bearer":["content:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Article id or slug."},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/articles/{id}/publish":{"post":{"operationId":"publishArticle","tags":["Articles"],"summary":"Publish an article","description":"Makes it live (or publishes its new text), and the assistant answers from it.","security":[{"bearer":["content:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Article id or slug."},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"The live article.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/articles/{id}/unpublish":{"post":{"operationId":"unpublishArticle","tags":["Articles"],"summary":"Unpublish an article","description":"Takes it off the help center; it stays as a draft.","security":[{"bearer":["content:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Article id or slug."},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"The article.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/articles/{id}/restore":{"post":{"operationId":"restoreArticle","tags":["Articles"],"summary":"Restore a deleted article","description":"Brings an article back from Recently deleted.","security":[{"bearer":["content:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"The article.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/articles/{id}/drafts":{"get":{"operationId":"listArticleDrafts","tags":["Drafts"],"summary":"List an article's drafts","description":"Pending proposed edits to this article.","security":[{"bearer":["content:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Article id or slug."},{"name":"start_cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page."},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"Pending edits.","content":{"application/json":{"schema":{"type":"object","required":["results","has_more","next_cursor"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Draft"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as start_cursor for the next page; null on the last page."}}}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createArticleDraft","tags":["Drafts"],"summary":"Propose an edit","description":"Proposes the article's full new text for review, without changing the live article. It shows up in Drafts → To review and in GET /drafts.\n\n```bash\ncurl -X POST \"https://usedocs.app/v1/articles/export-invoices/drafts\" \\\n  -H \"Authorization: Bearer $USEDOCS_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"contentMarkdown\":\"…the whole article, edited…\",\"reason\":\"CSV export moved under Reports\"}'\n```","security":[{"bearer":["content:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Article id or slug."},{"name":"format","in":"query","schema":{"type":"string","enum":["markdown","html"],"default":"markdown"},"description":"contentMarkdown (default) or contentHtml."},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contentMarkdown"],"properties":{"contentMarkdown":{"type":"string"},"title":{"type":"string"},"reason":{"type":"string"},"sourceUrl":{"type":"string","description":"The PR, issue, or page behind the edit."}}}}}},"responses":{"201":{"description":"The proposed edit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftDetail"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/drafts":{"get":{"operationId":"listDrafts","tags":["Drafts"],"summary":"List drafts","description":"Everything waiting for review, newest first.\n\n```bash\ncurl \"https://usedocs.app/v1/drafts?type=edit\" \\\n  -H \"Authorization: Bearer $USEDOCS_API_KEY\"\n```","security":[{"bearer":["content:read"]}],"parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["edit","new_article","gap_draft"]}},{"name":"article_id","in":"query","schema":{"type":"string"}},{"name":"start_cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page."},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"Drafts.","content":{"application/json":{"schema":{"type":"object","required":["results","has_more","next_cursor"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Draft"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as start_cursor for the next page; null on the last page."}}}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/drafts/{id}":{"get":{"operationId":"getDraft","tags":["Drafts"],"summary":"Get a draft","description":"The draft's full text; for an edit, also a unified diff against the live article and whether the article changed since (conflict).","security":[{"bearer":["content:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Draft id: edit_…, article_…, or gap_…."},{"name":"format","in":"query","schema":{"type":"string","enum":["markdown","html"],"default":"markdown"},"description":"contentMarkdown (default) or contentHtml."},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"The draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftDetail"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateDraft","tags":["Drafts"],"summary":"Update a draft","description":"Changes a pending draft's title or text before it's applied.","security":[{"bearer":["content:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Draft id: edit_…, article_…, or gap_…."},{"name":"format","in":"query","schema":{"type":"string","enum":["markdown","html"],"default":"markdown"},"description":"contentMarkdown (default) or contentHtml."},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"contentMarkdown":{"type":"string"}}}}}},"responses":{"200":{"description":"The draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftDetail"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/drafts/{id}/apply":{"post":{"operationId":"applyDraft","tags":["Drafts"],"summary":"Apply a draft","description":"Approves it: an edit updates its article (live at once on a live article); a new article or a draft from customer questions is published. For an edit you can send the text you want instead.\n\n```bash\ncurl -X POST \"https://usedocs.app/v1/drafts/edit_123/apply\" \\\n  -H \"Authorization: Bearer $USEDOCS_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'\n```","security":[{"bearer":["content:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Draft id: edit_…, article_…, or gap_…."},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"contentMarkdown":{"type":"string","description":"Edits only: apply this text instead of the proposal."}}}}}},"responses":{"200":{"description":"Applied.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/drafts/{id}/dismiss":{"post":{"operationId":"dismissDraft","tags":["Drafts"],"summary":"Dismiss a draft","description":"Declines it. A dismissed new article moves to Recently deleted.","security":[{"bearer":["content:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Draft id: edit_…, article_…, or gap_…."},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"Dismissed.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/articles/{id}/revisions":{"get":{"operationId":"listRevisions","tags":["Revisions"],"summary":"List revisions","description":"Earlier versions of an article, newest first (up to 50).","security":[{"bearer":["content:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Article id or slug."},{"name":"start_cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page."},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"Versions.","content":{"application/json":{"schema":{"type":"object","required":["results","has_more","next_cursor"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Revision"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as start_cursor for the next page; null on the last page."}}}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/articles/{id}/revisions/{revisionId}":{"get":{"operationId":"getRevision","tags":["Revisions"],"summary":"Get a revision","description":"One earlier version's text.","security":[{"bearer":["content:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Article id or slug."},{"name":"revisionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["markdown","html"],"default":"markdown"},"description":"contentMarkdown (default) or contentHtml."},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"The version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Revision"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/articles/{id}/revisions/{revisionId}/diff":{"get":{"operationId":"diffRevision","tags":["Revisions"],"summary":"Diff a revision","description":"A unified diff from this version to the current article, or to another version with compare_to.","security":[{"bearer":["content:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Article id or slug."},{"name":"revisionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"compare_to","in":"query","schema":{"type":"string"}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"The diff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Diff"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/articles/{id}/revisions/{revisionId}/restore":{"post":{"operationId":"restoreRevision","tags":["Revisions"],"summary":"Restore a revision","description":"Makes this version the current text (the replaced text is kept as a version).","security":[{"bearer":["content:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Article id or slug."},{"name":"revisionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"The article.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/collections":{"get":{"operationId":"listCollections","tags":["Collections"],"summary":"List collections","description":"In help center order.","security":[{"bearer":["content:read"]}],"parameters":[{"name":"start_cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page."},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"Collections.","content":{"application/json":{"schema":{"type":"object","required":["results","has_more","next_cursor"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as start_cursor for the next page; null on the last page."}}}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createCollection","tags":["Collections"],"summary":"Create a collection","description":"A new group of articles.","security":[{"bearer":["content:write"]}],"parameters":[{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"icon":{"type":"string","description":"An emoji."},"visibility":{"type":"string","enum":["public","authenticated"]}}}}}},"responses":{"201":{"description":"The collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/collections/{id}":{"get":{"operationId":"getCollection","tags":["Collections"],"summary":"Get a collection","description":"By id or slug.","security":[{"bearer":["content:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"The collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateCollection","tags":["Collections"],"summary":"Update a collection","description":"Title, description, slug, icon, visibility, or order.","security":[{"bearer":["content:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":["string","null"]},"slug":{"type":"string"},"icon":{"type":["string","null"]},"visibility":{"type":"string","enum":["public","authenticated"]},"sortOrder":{"type":"integer"}}}}}},"responses":{"200":{"description":"The collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteCollection","tags":["Collections"],"summary":"Delete a collection","description":"Its articles stay, without a collection.","security":[{"bearer":["content:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/changelog/entries":{"get":{"operationId":"listChangelogEntries","tags":["Changelog"],"summary":"List changelog entries","description":"Newest first.","security":[{"bearer":["content:read"]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["all","draft","published","archived"]}},{"name":"format","in":"query","schema":{"type":"string","enum":["markdown","html"],"default":"markdown"},"description":"contentMarkdown (default) or contentHtml."},{"name":"start_cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page."},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"Entries.","content":{"application/json":{"schema":{"type":"object","required":["results","has_more","next_cursor"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ChangelogEntry"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as start_cursor for the next page; null on the last page."}}}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createChangelogEntry","tags":["Changelog"],"summary":"Create a changelog entry","description":"Creates a draft entry. Publish it with POST /changelog/entries/{id}/publish.\n\n```bash\ncurl -X POST \"https://usedocs.app/v1/changelog/entries\" \\\n  -H \"Authorization: Bearer $USEDOCS_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"title\":\"Faster CSV exports\",\"contentMarkdown\":\"Exports of 10,000 invoices now take seconds.\"}'\n```","security":[{"bearer":["content:write"]}],"parameters":[{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","contentMarkdown"],"properties":{"title":{"type":"string"},"contentMarkdown":{"type":"string"},"sourceUrl":{"type":"string"}}}}}},"responses":{"201":{"description":"The entry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangelogEntry"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/changelog/entries/{id}":{"get":{"operationId":"getChangelogEntry","tags":["Changelog"],"summary":"Get a changelog entry","description":"By id or slug.","security":[{"bearer":["content:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["markdown","html"],"default":"markdown"},"description":"contentMarkdown (default) or contentHtml."},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"The entry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangelogEntry"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateChangelogEntry","tags":["Changelog"],"summary":"Update a changelog entry","description":"Title or text.","security":[{"bearer":["content:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["markdown","html"],"default":"markdown"},"description":"contentMarkdown (default) or contentHtml."},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"contentMarkdown":{"type":"string"}}}}}},"responses":{"200":{"description":"The entry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangelogEntry"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/changelog/entries/{id}/publish":{"post":{"operationId":"publishChangelogEntry","tags":["Changelog"],"summary":"Publish a changelog entry","description":"Shows it in the help center's changelog and RSS feed.","security":[{"bearer":["content:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"The entry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangelogEntry"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/changelog/entries/{id}/unpublish":{"post":{"operationId":"unpublishChangelogEntry","tags":["Changelog"],"summary":"Unpublish a changelog entry","description":"Back to draft.","security":[{"bearer":["content:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"The entry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangelogEntry"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks":{"get":{"operationId":"listTasks","tags":["Tasks"],"summary":"List tasks","description":"Recent tasks, newest first.","security":[{"bearer":["content:read"]}],"parameters":[{"name":"start_cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page."},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"Tasks.","content":{"application/json":{"schema":{"type":"object","required":["results","has_more","next_cursor"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as start_cursor for the next page; null on the last page."}}}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createTask","tags":["Tasks"],"summary":"Create a task","description":"Starts background work that ends in drafts for review; nothing is published. Poll GET /tasks/{id} or subscribe to the `task.completed` webhook.\n\n- **Write or update docs:** send `description` (what's needed).\n- **Document a code change:** send `change` with the diff (or changed paths and commits). usedocs reads it against your docs and proposes edits to the articles it affects, new articles it needs, and a changelog entry. This is the same job a merged pull request runs on the GitHub app, so it works from any CI or code host.\n\nSend an `Idempotency-Key` header so a retried CI job doesn't start the task twice (kept for 24 hours).\n\n```bash\ngit diff origin/main...HEAD | jq -Rs '{change: {kind: \"pr\", title: \"Add CSV export\", url: \"https://github.com/acme/app/pull/42\", diff: .}}' | \\\n  curl -X POST \"https://usedocs.app/v1/tasks\" -H \"Authorization: Bearer $USEDOCS_API_KEY\" \\\n  -H \"Content-Type: application/json\" -H \"Idempotency-Key: $CI_COMMIT_SHA\" --data-binary @-\n```","security":[{"bearer":["content:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","description":"What should change in the docs. Required without change."},"title":{"type":"string"},"change":{"type":"object","required":["title"],"properties":{"kind":{"type":"string","enum":["pr","release"],"default":"pr"},"title":{"type":"string","description":"The PR or release title."},"description":{"type":"string","description":"The PR body or release notes."},"diff":{"type":"string","description":"A unified diff (git diff). Up to 200 KB is read."},"changedPaths":{"type":"array","items":{"type":"string"}},"commits":{"type":"array","items":{"type":"string"},"description":"Commit subjects."},"url":{"type":"string","description":"Link to the PR or release."},"version":{"type":"string","description":"Release version or tag."},"repo":{"type":"string","description":"owner/name, when it's not the repo connected to usedocs."}}}}}}}},"responses":{"201":{"description":"The task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks/{id}":{"get":{"operationId":"getTask","tags":["Tasks"],"summary":"Get a task","description":"Its status and, once completed, the drafts it made.","security":[{"bearer":["content:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"The task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/gaps":{"get":{"operationId":"listGaps","tags":["Insights"],"summary":"List unanswered questions","description":"Questions the assistant couldn't answer from your docs, most asked first.","security":[{"bearer":["content:read"]}],"parameters":[{"name":"start_cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page."},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"Questions.","content":{"application/json":{"schema":{"type":"object","required":["results","has_more","next_cursor"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Gap"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as start_cursor for the next page; null on the last page."}}}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/health":{"get":{"operationId":"getHealth","tags":["Insights"],"summary":"Get doc health","description":"How many live articles match your code and website, and which need review.","security":[{"bearer":["content:read"]}],"parameters":[{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"Doc health.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/checks":{"post":{"operationId":"createCheck","tags":["Insights"],"summary":"Check articles","description":"Checks one live article (articleId) or all of them against your code and website. Fixes land in Drafts.","security":[{"bearer":["content:write"]}],"parameters":[{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"articleId":{"type":"string"}}}}}},"responses":{"202":{"description":"Queued.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"get":{"operationId":"listWebhooks","tags":["Webhooks"],"summary":"List webhook endpoints","description":"Endpoints and the events they get.","security":[{"bearer":["content:read"]}],"parameters":[{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"Endpoints.","content":{"application/json":{"schema":{"type":"object","required":["results","has_more","next_cursor"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as start_cursor for the next page; null on the last page."}}}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createWebhook","tags":["Webhooks"],"summary":"Create a webhook endpoint","description":"An HTTPS URL and the events to send. The response has the signing secret, shown once. Events: article.published, article.updated, article.unpublished, article.deleted, edit.proposed, draft.created, changelog_entry.published, task.completed, conversation.escalated, lead.created. Each delivery is signed: `usedocs-signature: t=…,v1=HMAC-SHA256(t.body)`.","security":[{"bearer":["content:write"]}],"parameters":[{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"The endpoint, with secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}":{"get":{"operationId":"getWebhook","tags":["Webhooks"],"summary":"Get a webhook endpoint","description":"With its last deliveries.","security":[{"bearer":["content:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"The endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateWebhook","tags":["Webhooks"],"summary":"Update a webhook endpoint","description":"URL, events, on or off, or a new secret (rotateSecret: true).","security":[{"bearer":["content:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"rotateSecret":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteWebhook","tags":["Webhooks"],"summary":"Delete a webhook endpoint","description":"Stops deliveries to it.","security":[{"bearer":["content:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/test":{"post":{"operationId":"testWebhook","tags":["Webhooks"],"summary":"Send a test event","description":"Sends a sample article.published event to this endpoint now.","security":[{"bearer":["content:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"bot_id","in":"query","schema":{"type":"string"},"description":"Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header."}],"responses":{"200":{"description":"How the delivery went.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request is missing something or has a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The workspace is paused; reads still work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read key on a write, or a key for another bot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A workspace API key: ud_live_…"}},"schemas":{"Error":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","description":"What went wrong, for people."},"code":{"type":"string","description":"Machine-readable: unauthorized, insufficient_scope, plan_inactive, rate_limited, not_found, bot_required, invalid_…"}}},"Article":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","in_review","published","archived"]},"description":{"type":["string","null"]},"collectionId":{"type":["string","null"]},"locale":{"type":"string"},"visibility":{"type":"string","enum":["public","authenticated"]},"url":{"type":["string","null"],"description":"The live page, when published."},"contentMarkdown":{"type":"string","description":"With format=markdown (default)."},"contentHtml":{"type":"string","description":"With format=html."},"publishedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Draft":{"type":"object","properties":{"id":{"type":"string","description":"edit_…, article_…, or gap_…"},"type":{"type":"string","enum":["edit","new_article","gap_draft"]},"articleId":{"type":["string","null"]},"title":{"type":"string"},"source":{"type":"string","enum":["code","customers","requests","import","translations"]},"detail":{"type":"string"},"reason":{"type":"string"},"conflict":{"type":"boolean","description":"The article changed after the edit was proposed."},"live":{"type":"boolean","description":"The edited article is published."},"originUrl":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}},"DraftDetail":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","dismissed"]},"articleId":{"type":["string","null"]},"title":{"type":"string"},"contentMarkdown":{"type":"string"},"diff":{"type":"string","description":"Edits: a unified diff from the live article to the proposal."},"linesAdded":{"type":"integer"},"linesRemoved":{"type":"integer"},"reason":{"type":"string"},"evidence":{"type":"object","properties":{"url":{"type":["string","null"]},"label":{"type":["string","null"]},"files":{"type":"array","items":{"type":"string"}}}},"conflict":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"Revision":{"type":"object","properties":{"id":{"type":"string"},"articleId":{"type":"string"},"title":{"type":"string"},"contentMarkdown":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"Diff":{"type":"object","properties":{"articleId":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"diff":{"type":"string"},"added":{"type":"integer"},"removed":{"type":"integer"}}},"Collection":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"description":{"type":["string","null"]},"icon":{"type":["string","null"]},"visibility":{"type":"string"},"sortOrder":{"type":"integer"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}}},"ChangelogEntry":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","published","archived"]},"contentMarkdown":{"type":"string"},"sourceUrl":{"type":["string","null"]},"publishedAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}}},"Task":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","description":"change, write_article, document_feature, refresh_article, replace_term, draft_gaps, check_all, audit"},"title":{"type":"string"},"status":{"type":"string","enum":["queued","in_progress","completed","failed"]},"result":{"type":["object","null"],"properties":{"draftIds":{"type":"array","items":{"type":"string"}},"changelogEntryId":{"type":["string","null"]},"skipped":{"type":"boolean","description":"The change needed no doc updates."},"reason":{"type":["string","null"]},"impact":{"type":["string","null"]}}},"error":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}},"Gap":{"type":"object","properties":{"question":{"type":"string"},"count":{"type":"integer"},"lastAskedAt":{"type":"string","format":"date-time"}}},"Health":{"type":"object","properties":{"counts":{"type":"object"},"lastCheckedAt":{"type":["string","null"]},"needsReview":{"type":"array","items":{"type":"object","properties":{"articleId":{"type":"string"},"title":{"type":"string"},"reason":{"type":"string"},"pendingEdits":{"type":"integer"}}}}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"created_at":{"type":"string"},"secret_hint":{"type":"string"},"secret":{"type":"string","description":"Only when created or rotated."}}}}}}