REST API reference

The Doxbrix REST API lets you automate the same work you do in the app: list projects, read and update pages, search, ask the project's assistant, manage assistant keys and access tokens, and control Git sync. This page describes authentication, request and response conventions, every supported endpoint with its required scope, and the error codes you handle in scripts.

The dxb CLI, the TypeScript SDK, and the MCP server all call this API, so the scopes and errors below apply to them too.

Scope of this reference

• Base URL: https://app.doxbrix.com/api/v1
• Format: JSON request and response bodies. Send Content-Type: application/json with every request that has a body.
• Included: the public /api/v1 endpoints listed on this page.
• Not included: the bundle and deployment endpoints that dxb push uses internally. Use the CLI for those workflows.

Authentication

Send a personal access token as a bearer token in the Authorization header. Tokens start with dxb_. To create one, see Create and revoke access tokens.

curl https://app.doxbrix.com/api/v1/me \
  -H "Authorization: Bearer $DOXBRIX_TOKEN"

{ "id": "7b1e2c4d-5f60-4a71-8b92-a3b4c5d6e7f8", "email": "teammate@example.com", "name": "Sam Rivera" }

A request without a valid token returns 401 with the code unauthorized. Requests from the Doxbrix app itself can use the signed-in session instead of a token; a session request from another origin is rejected with 403 and the code invalid_origin.

Scopes

Each endpoint requires one scope. A token can only call endpoints whose scope it holds, and a request with a missing scope returns 403 with the code insufficient_scope.

A token created without explicit scopes receives docs:read, docs:write, and project:read.

Project-scoped tokens

A project-scoped token works only for one project. Requests for other projects return 404. A project-scoped token cannot list, create, or revoke workspace tokens; those requests return 403 with the code forbidden.

Request conventions

• Project identifiers. Wherever a path contains :projectId, you can pass the project UUID or its slug, for example pocketbase-docs.
• Page identifiers. :pageId and body fields such as spaceId, parentId, and navItemId are UUIDs.
• Access checks. Beyond the token scope, you also need a role in the project that allows the action. For example, updating a page requires editor access and connecting Git requires admin access. See Roles and permissions.

Errors

Every error response is JSON with a human-readable error message and, in most cases, a stable code:

{
  "error": "This token is missing the 'docs:write' scope.",
  "code": "insufficient_scope",
  "requestId": "0f3a8c1e-2b7d-4e59-9a10-6c4d2e8f1b37"
}

Authentication failures and unexpected server errors also include a requestId field and an x-request-id response header. Include the request ID when you contact support.

Account and tokens

The dxb login command uses the device authorization endpoints /auth/device/start, /auth/device/approve, and /auth/device/poll. Use dxb login rather than calling them directly.

Create a token

curl -X POST https://app.doxbrix.com/api/v1/auth/tokens \
  -H "Authorization: Bearer $DOXBRIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-docs-lint","scopes":["docs:read"],"expiresInDays":90}'

The raw token value is returned only in this response. A token can grant only scopes it already holds, and a new token never expires later than the token that created it. Token creation with a bearer token is limited to 30 requests per hour per user.

Projects

Create a project accepts name (1–60 characters, required), slug (lowercase letters, digits, and hyphens, up to 80), description (up to 160), visibility (public or private), editorMode (block or wysiwyg), and seedTemplate (boolean). Projects created through the API are empty unless seedTemplate is true.

Update settings accepts:

curl -X PATCH https://app.doxbrix.com/api/v1/projects/pocketbase-docs/settings \
  -H "Authorization: Bearer $DOXBRIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"theme":"dark","primaryColor":"#4f46e5"}'

Spaces and structure

The structure PATCH body takes one operation, selected by op:

curl -X PATCH https://app.doxbrix.com/api/v1/projects/pocketbase-docs/structure \
  -H "Authorization: Bearer $DOXBRIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"op":"rename_item","navItemId":"9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d","title":"Install PocketBase"}'

Pages

List pages accepts the query parameters space (a space filter), status (draft, in_review, published, unpublished, or archived), and limit.

Create a page accepts spaceId (required), title (1–200 characters, required), parentId (optional, or null), and content (optional Markdown).

curl -X POST https://app.doxbrix.com/api/v1/projects/pocketbase-docs/pages \
  -H "Authorization: Bearer $DOXBRIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spaceId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","title":"Back up your data","content":"## Before you begin\n\nStop the server."}'

Publish follows the project's approval rules and never skips review:

{ "status": "in_review", "published": false, "message": "Submitted for review, this project requires approval before publishing." }

When no approval is required, the response has "status": "published", "published": true, and the message Page published. For the approval rules, see Page lifecycle and approval policies.

Search, AI, and content tools

curl "https://app.doxbrix.com/api/v1/projects/pocketbase-docs/search?q=backup&limit=5" \
  -H "Authorization: Bearer $DOXBRIX_TOKEN"

Assistant keys and project tokens

Headless assistant

POST /assistant/ask and POST /assistant/ask/stream answer reader questions from an external website or backend. They do not use access tokens. Send the assistant key in the X-Assistant-Key header instead. Browser calls must come from an origin on the key's allow list; otherwise the API returns 403 with Origin not allowed for this key. The stream endpoint returns server-sent events. For setup, see Embed the assistant on another website.

Git sync

Connect a repository accepts:

curl -X POST https://app.doxbrix.com/api/v1/projects/pocketbase-docs/git \
  -H "Authorization: Bearer $DOXBRIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider":"github","repoFullName":"acme/docs","branch":"main","basePath":"docs","outboundMode":"pr","conflictPolicy":"git_wins","token":"github_pat_example"}'

For the full workflow, see Sync a project with a Git repository and Resolve Git sync conflicts.

Next steps