# API docs on GitBook

How the AutoGPT Platform API docs at `agpt.co/docs/platform/api-and-integrations/` are built, and what has to be set up in GitBook for them.

## What comes from where

- **Guides** are Markdown in `docs/platform/integrating/`, listed in `docs/platform/SUMMARY.md` under "API & Integrations". They reach GitBook with every other page through `docs-gitbook-sync.yml` (master to the `gitbook` branch).
- **The API reference** is generated by GitBook from an OpenAPI spec stored in the GitBook organization as `autogpt-api-v2`. The `builtin:openapi` entry under "API reference" in `SUMMARY.md` names that slug and generates one page per operation (`grouping: by-operation`), plus a models page and a spec download link.
- `.github/workflows/docs-gitbook-openapi.yml` republishes the spec from master whenever `backend/api/external/` changes, so the reference follows the same commit as the guides.
- The spec's own metadata shapes the reference: tag titles (`x-page-title`) name the sections, `servers` feed GitBook's "Test it" panel and every operation page, and `x-enable-proxy` sends "Test it" requests through GitBook's proxy because the API doesn't allow the docs site's origin. These live in `backend/api/external/v2/app.py`.

## One-time setup

1. In GitBook, create an API token for an organization admin, and store it as the repository secret `GITBOOK_TOKEN`.
2. Store the organization ID (the segment after `/o/` in GitBook app URLs) as the repository variable `GITBOOK_ORGANIZATION_ID`.
3. Publish the spec once by hand **before** the release that first ships the `builtin:openapi` entry to master, so the `autogpt-api-v2` spec exists when GitBook imports the new `SUMMARY.md`. The workflow can't do this first publish: GitHub offers `workflow_dispatch` only for a workflow already on the default branch, and this one reaches master in that same release. From `autogpt_platform/backend` on the release branch, run the workflow's own two steps:

   ```bash
   poetry run export-api-schema --api v2 --pretty --output /tmp/autogpt-api-v2.json
   GITBOOK_TOKEN=... npx --yes @gitbook/cli@0.32.9 openapi publish \
     --spec autogpt-api-v2 --organization "$GITBOOK_ORGANIZATION_ID" \
     /tmp/autogpt-api-v2.json
   ```

   After that release, every push to master that changes `backend/api/external/` republishes it, and the workflow can be run by hand from master.
4. Make the spec public in GitBook (OpenAPI → `autogpt-api-v2` → visibility). "Test it" only appears for a spec with a public URL.

## Site settings worth keeping on

These are GitBook site settings, not files in this repository:

- **Page actions**, including "Copy page", "View as Markdown", "Open in ChatGPT / Claude" and the MCP actions. Turning page actions off also disables the docs MCP server at `agpt.co/docs/~gitbook/mcp`, which the "Build with AI coding agents" page tells people to use.
- **AI assistant**, if the plan allows it. The `.md` version of every page links its `?ask=` endpoint for agents.

`llms.txt`, `llms-full.txt` and the `.md` page versions are automatic. Each guide's `description:` frontmatter becomes its line in `llms.txt`, so keep one on every page.

## Keeping the guides true

Every request and response in the guides was copied from a running instance, and the Quickstart's scripts run as written. When the API changes, run the changed examples against an instance built from the branch before merging; the Quickstart scripts take `AUTOGPT_API_URL` and `AUTOGPT_API_KEY` and exit non-zero unless the sample agent answers `Hello, Ada!`.