REST API overview

What this is

The ComStack REST API — the HTTP surface the MCP server is built on. It covers page management, publishing, live voice sessions, project configuration, authentication, and templates.

Base URL: https://api.comstack.ai

The MCP server wraps these same operations. If you’re using Claude, Cursor, or another MCP client, you don’t need to call the REST API directly. Use it when integrating from a custom server, webhook, or CI pipeline.

How it works

Authentication

Two methods:

OAuth Bearer token — for user accounts. Obtained via the OAuth flow; send as Authorization: Bearer <token>. See Authentication reference.
Service API key — for headless callers. Set x-project-id and x-api-key headers. Generate keys in project settings.

Response format

Successful responses return JSON. Errors return { "error": "..." }:

Status	Meaning
`400`	Invalid request — missing or malformed arguments
`401`	Authentication required
`403`	Insufficient role, module disabled, or trial expired
`404`	Resource not found
`413`	Payload too large (1 MB general; 10 MB image upload)
`429`	Rate limit exceeded
`500`	Internal error

Rate limits

Per-IP, 60-second sliding window:

Endpoint	Limit
`POST /mcp`	60 requests/min
`/oauth/*`	30 requests/min
Auth failures (401 responses)	10/min before 429 kicks in

Endpoint groups

OAuth and authentication

/.well-known/oauth-authorization-server, /oauth/register, /oauth/authorize, /oauth/token

Projects

GET/POST /api/projects, GET/PATCH/DELETE /api/projects/:id, members, domains, modules, settings

Pages (knowledge)

Create, edit (/docs/edit/open, /edit/save, /edit/discard), list, publish flow, visibility

Custom pages

POST /api/projects/:id/docs/edit/upload-custom-page — for HTML/Astro custom page bodies

Publishing

POST /api/projects/:id/publish, POST .../publish/confirm, GET .../publish/history

Publishing is a two-step flow: dry-run builds a manifest + confirmation token; confirm promotes and deploys. See Publish reference.

Live voice

POST /api/live/session, /session/resume, /tools/execute, /twilio/voice

/api/projects/:id/sidebar-groups, /api/projects/:id/header-nav-items

Templates

/api/templates/doc, /api/templates/project, /api/projects/:id/templates

Ingestion (Chrome Extension)

/api/projects/:id/ingest/* — capture, extract, and save pages from the Chrome extension

API keys

/api/projects/:id/keys

Account

/api/accounts/me, /api/account/connectors/claude/*

When to use it

Use case	Recommended path
AI assistant managing content	MCP server — the tools abstract the API and handle auth
Server-side integration, CI/CD	REST API — more control, no MCP client dependency
Webhook receiver	REST API

Example

Fetch project details with a Bearer token:

curl https://api.comstack.ai/api/projects/YOUR_PROJECT_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Call the MCP endpoint with a service key:

curl -X POST https://api.comstack.ai/mcp \
  -H "Content-Type: application/json" \
  -H "x-project-id: YOUR_PROJECT_ID" \
  -H "x-api-key: YOUR_SERVICE_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get-project-state","arguments":{"project_id":"YOUR_PROJECT_ID"}}}'

Common errors

Error	Cause	Fix
`401 Unauthorized`	Missing or expired token	Re-authenticate or regenerate the API key
`403 Trial expired`	The project’s trial period ended	Upgrade the plan to restore access
`403 Insufficient permission`	Caller’s role is below the endpoint’s requirement	Check your role and ensure you’re calling with the right credentials
`413 Payload Too Large`	Request body exceeds the limit	Reduce payload size or use the chunked image upload endpoint
`429 Too Many Requests`	Rate limit hit	Back off and retry after the `Retry-After` header value

Authentication reference — tokens, API keys, role mapping
Publish reference — two-step draft-to-live flow
MCP server — the same operations via MCP tools