Public API and AI assistants

Read the docs from your own tools, and let scripts and AI assistants propose changes as pull requests, with API keys that read exactly what their audience may see.

API keys

Staff create keys in the admin console under API & AI, or with POST /admin/api/api-keys; see Admin API reference. A key looks like opd_prefix_secret and is shown once. Only a hash of the secret is stored. Send it as Authorization: Bearer opd_….

Each key has:

Scopes, which say what it can do: read (the published docs), write (read the source, validate, save changes and open pull requests), publish (also merge them when the repository's rules allow) and builds (see and start builds). publish includes write, and both include read.
An audience, which says whose view of the docs it reads:
- staff: everything, with conditional content labelled, any live release line;
- one org: exactly what that org's readers see, on their release line;
- public: what anonymous visitors see; only on public sites.
Every answer goes through the same filtering as the site, so a key never sees a topic, title, link, image or search hit its audience could not.
An expiry (30, 90 or 365 days, or never). Revoking a key in the console or with DELETE /admin/api/api-keys/:id takes effect at once.

Each key may make 300 requests a minute; more get 429 with Retry-After.

Routes

The base path is /api/v1. GET /api/v1/openapi.json describes every route in OpenAPI 3.1 and needs no key.

Route	Scope	What it does
`GET /me`	read	The calling key: name, scopes, audience, expiry.
`GET /versions`	read	Live release lines the key can read, and its default one.
`GET /nav`	read	The navigation tree: titles, topic ids, URLs.
`GET /topics`	read	Every topic the key can read: id, title, short description, URL.
`GET /topics/id`	read	One topic. `format` is `markdown` (default), `html` or `text`. Links point at the docs site.
`GET /search?q=`	read	Full-text search, best first; `limit` 1 to 50.
`GET /source/files`, `GET /source/files/path`	write	The docs source on the published branch, or with `ref=working` on the key's working branch.
`POST /validate`	write	Validates `{"files": [{"path", "content"}]}` laid over the working branch, without saving. Returns the diagnostics.
`GET /changes`	write	The key's working branch, its pull request and what still blocks merging.
`POST /changes`	write	Saves files as one commit to the key's working branch. Optional `message`, and `expectSha` to refuse the save if the file changed since it was read.
`POST /changes/publish`	write	Opens, or updates, one pull request for the working branch. With `{"merge": true}` and the `publish` scope, merges it when the branch's review rules allow.
`GET /builds`, `POST /builds`	builds	Recent builds; build the release refs now, or one `ref`.

Staff keys may add version (a release line such as 2) to the read routes. Org and public keys read their own line; asking for another gets 403.

How changes work

Writes use the web editor's workflow; see Run the web editor. Each key is an author of its own: its commits are credited to key name (API key), on its own working branch. The published branch is merged in after each save, never rebased. Publishing opens one pull request, which your branch protection and reviewers govern like any other. Files must be .dita, .ditamap or .bookmap inside the docs folder. Malformed XML is refused, and validation errors stop publishing.

On repositories that require signed commits, keys cannot save: the app cannot sign as a person. See Verified commits.

Example

curl -H "Authorization: Bearer $OPEND_KEY" \
  "https://docs.example.com/api/v1/search?q=install"

curl -H "Authorization: Bearer $OPEND_KEY" \
  "https://docs.example.com/api/v1/topics/topics/install"

AI assistants

On managed hosting, the API & AI page shows the address of the OpenD MCP (Model Context Protocol) connector. Add it once as a custom connector in an AI assistant such as Claude and sign in with an OpenD account (email and password), Google, GitHub or an emailed link. The assistant sees every OpenD site where you are a reader, exactly as you see it: everything on sites where you are staff, your organisation's view elsewhere. If you allow it, it can also propose changes as pull requests on sites where you are staff. An OpenD account counts as your address only once you confirm it from the email it sends, with the account's password; until then the assistant reads public docs only.

For each site it uses, the connector creates an API key named MCP: followed by the person's email, with only the access that person has. Keys appear in the list on the API & AI page; revoke one to cut that assistant off from the site. Self-hosted sites can point any MCP or OpenAPI client at /api/v1 with a key.