# Docs API

Read and change your help center from your own tools and CI, at `https://usedocs.app/v1`: articles, drafts waiting for review (with diffs), revisions, collections, the changelog, unanswered questions, doc health, tasks, and webhooks. The full reference is [usedocs.app/v1/openapi.json](https://usedocs.app/v1/openapi.json).

- **Auth.** `Authorization: Bearer ud_live_…`. A key that covers several bots names one with `?bot_id=` or the `Usedocs-Bot` header; `GET /v1/bots` lists them.
- **Pages.** Lists take `page_size` (1 to 100, default 20) and `start_cursor`, and return `{results, has_more, next_cursor}`.
- **Content.** Articles come as `contentMarkdown`, or `contentHtml` with `?format=html`.
- **Errors.** `{error, code}` with an HTTP status: `insufficient_scope`, `plan_inactive` (paused workspace; reads still work), `rate_limited`, `bot_required`, `not_found`.
- **Drafts.** Everything waiting for review has a typed id: `edit_…` (a proposed edit to an article), `article_…` (a new article usedocs wrote), `gap_…` (a draft from customer questions). `GET /v1/drafts/{id}` returns the text and a unified diff; `POST /v1/drafts/{id}/apply` approves it.

```
curl 'https://usedocs.app/v1/articles?status=published&page_size=50' \
  -H "Authorization: Bearer $USEDOCS_API_KEY"
```

To send changes from your pipeline, see [Update the docs from CI](https://help.usedocs.app/update-docs-from-ci).