---
title: "REST API overview"
description: "Base URL, authentication, response format, error codes, rate limits, and endpoint groups for the REST API."
url: "https://comstack.ai/docs/api/"
---
## 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](/docs/api/authentication.md).
- **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](/docs/api/publish.md).

### Live voice
`POST /api/live/session`, `/session/resume`, `/tools/execute`, `/twilio/voice`

### Sidebar and navigation
`/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:

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

Call the MCP endpoint with a service key:

```bash
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 |

## Related

- [Authentication reference](/docs/api/authentication.md) — tokens, API keys, role mapping
- [Publish reference](/docs/api/publish.md) — two-step draft-to-live flow
- [MCP server](/docs/mcp.md) — the same operations via MCP tools