Start Here
REST API
HTTP endpoints for managing projects, generations, and OAuth sign-in for connected agents
Overview
The Doxa REST API is the HTTP interface behind the dashboard and the connected-agent sign-in flow. It provides endpoints to create, read, and delete projects; manage a project's GitHub repository, shell data, and preview visibility; start and monitor documentation generations; and run the OAuth authorization server that MCP clients use to sign in.
Callers are the Doxa dashboard, MCP clients that complete OAuth sign-in, and developers who build on Doxa programmatically. Each endpoint acts on the projects and generations of the signed-in user, including team projects the user can access.
Base URL
All endpoint paths in this section are relative to the Doxa API server:
https://api.doxa.soFor example, listing projects is a GET request to https://api.doxa.so/projects.
Authentication
The reference does not define a separate API key scheme. Project and generation endpoints run for the signed-in user. Agents that use the Doxa MCP server obtain access tokens through the OAuth endpoints described below; see Connect an AI Agent with MCP for the sign-in steps.
Resources
The API has three resource groups. Each group has its own reference section:
Create, read, and delete projects and their repository, shell, and preview settings.
Start, monitor, and manage documentation generations and the generation cache.
OAuth authorization server endpoints used by MCP clients to sign in.
The table below lists every endpoint in the reference.
| Method | Path | Description | Reference |
|---|---|---|---|
| GET | /projects | List the signed-in user's projects. | List projects |
| POST | /projects | Create a new project. | Create a project |
| POST | /projects/example | Create a project from the starter example docs. | Create example project |
| PUT | /projects/{projectId}/repository | Connect or change the GitHub repository for a project. | Set project repository |
| GET | /projects/{projectId} | Fetch a project by ID. | Get a project |
| DELETE | /projects/{projectId} | Delete a project. | Delete a project |
| GET | /projects/{projectId}/shell | Fetch the data the dashboard shell needs for a project. | Get project shell |
| GET | /projects/{projectId}/preview-visibility | Read the preview visibility setting for a project. | Get preview visibility |
| PUT | /projects/{projectId}/preview-visibility | Change the preview visibility setting for a project. | Set preview visibility |
| POST | /projects/{projectId}/generate | Start a documentation generation for a project. | Start a generation |
| GET | /projects/{projectId}/generations | List a project's generations. | List generations |
| GET | /projects/{projectId}/generations/{generationId} | Fetch a single generation. | Get a generation |
| GET | /projects/{projectId}/generations/{generationId}/events | Read the events recorded for a generation. | List generation events |
| GET | /projects/{projectId}/generations/{generationId}/stream | Stream live generation updates as server-sent events. | Stream generation updates |
| POST | /projects/{projectId}/generations/{generationId}/cancel | Cancel a running generation. | Cancel a generation |
| POST | /projects/{projectId}/generations/{generationId}/rerun | Run a generation again. | Rerun a generation |
| POST | /projects/{projectId}/generations/{generationId}/resume | Resume a generation that stopped. | Resume a generation |
| POST | /projects/{projectId}/generations/{generationId}/promote | Promote a generation's output. | Promote a generation |
| DELETE | /projects/{projectId}/generations/{generationId} | Delete a generation record. | Delete a generation |
| GET | /projects/{projectId}/generation-cache | Read the project's generation cache. | Get generation cache |
| POST | /projects/{projectId}/generation-cache/clear | Clear the project's generation cache. | Clear generation cache |
| GET | /.well-known/oauth-authorization-server | OAuth authorization server metadata for MCP clients. | Get OAuth server metadata |
| GET | /oauth/authorize | Begin authorization; the user picks scopes and projects on the consent page. | Start OAuth authorization |
| POST | /oauth/token | Issue access and refresh tokens. Access tokens last 1 hour; refresh tokens last 30 days, or 14 days without use. | Exchange OAuth token |
| POST | /oauth/register | Register an MCP client. | Register OAuth client |
Errors from the API use a JSON body with an error object that contains a message and optional details. Validation failures return the same shape with a validation_failed code and a list of issues.