The doxa API allows you to programmatically manage your documentation projects, deployments, analytics, and workflows.

Base URL#

All API requests are made to:

http://localhost:3000/api

In production, replace localhost:3000 with your deployment domain.

Authentication#

The doxa API supports two authentication methods:

Session Cookie (Primary)#

Most API endpoints require an active user session. When you sign in through the web interface, NextAuth.js sets a session cookie (next-auth.session-token) that authenticates subsequent API requests.

Session-based authentication is used for:

  • Organization and project management
  • File operations in the editor
  • Analytics access
  • Settings configuration

API Keys (Coming Soon)#

API keys provide programmatic access for automation and integrations. Create an API key from your project settings:

1

Navigate to project settings

Open your project and go to Settings > API Keys.

2

Create a new key

Click "Create API Key" and give it a descriptive name.

3

Copy the key

The plaintext key is shown once. Store it securely - you won't be able to retrieve it again.

4

Use in requests

Pass the key in the Authorization header:

Authorization: Bearer doxa_YOUR_API_KEY_HERE

API keys grant full access to the project. Treat them like passwords and never commit them to version control.

Standard Error Responses#

All endpoints return consistent error shapes:

Single Error#

{ "error": "Not authenticated" }

Validation Error (422)#

When request validation fails, the response includes detailed field-level issues:

{ "error": "Validation failed", "issues": { "fieldErrors": { "name": ["String must contain at least 2 character(s)"] }, "formErrors": [] } }

Common HTTP Status Codes#

  • 200 - Success
  • 201 - Resource created
  • 400 - Bad request (business logic error)
  • 401 - Not authenticated
  • 403 - Insufficient permissions
  • 404 - Resource not found
  • 409 - Conflict (duplicate resource)
  • 422 - Validation failed
  • 500 - Internal server error

Role-Based Access#

Organization members have roles that determine API access:

  • OWNER - Full access, cannot be removed if they're the last owner
  • ADMIN - Manage settings, members, API keys, and delete projects
  • EDITOR - Create workflows, edit files, deploy, and publish
  • MEMBER - Read access to projects and analytics
  • VIEWER - Read-only access

Each endpoint specifies the minimum role required in its documentation.

Rate Limiting#

The Ask Docs endpoints enforce per-organization rate limits (default 30 requests per minute, configurable via ASK_RATE_LIMIT). When exceeded, the API returns a 429 response with a Retry-After header. All other endpoints currently have no enforced rate limits.

Pagination#

List endpoints that support pagination use query parameters:

  • take - Number of items to return (defaults vary by endpoint)
  • cursor - Opaque token for the next page (where supported)

Example:

GET /api/projects/{projectId}/workflows/{wid}/runs?take=20

Next Steps#

Explore the API by resource:

Organizations

Manage organizations and team members

Projects

Create and configure documentation projects

Files

Read and write documentation files

Deployments

Deploy and publish your docs

Workflows

Automate documentation tasks

Analytics

Track usage and engagement

Ask Docs

Search documentation with AI

Docs Index

Manage the search index