# REST API reference · Comma Docs

Canonical: https://commareports.com/docs/api

> Reference for the Comma Agent API: reports, revisions, diffs, comments, sharing, assets, reviews, routines, skills, connectors, and notifications — with methods and required token scopes.

# REST API reference

Base URL: `https://commareports.com/api/v1`. Every endpoint takes a Bearer
token in the `Authorization` header:

```
Authorization: Bearer comma_sk_…
```

Tokens carry [scopes](/docs/api-tokens); each endpoint below lists the scope
it requires. Requests and responses are JSON unless noted. Errors come back
as `{ "error": "…" }` with a conventional status code (`401` bad token,
`403` missing scope or no access to the report, `404` not found, `429` rate
limited).

## Reports

| Method  | Path                              | Scope           | What it does                                                                              |
| ------- | --------------------------------- | --------------- | ----------------------------------------------------------------------------------------- |
| `POST`  | `/reports`                        | `reports:write` | Create a report. Body: `html` (required, ≤ 5 MB), `title`, `description`, `visibility` (`private` \| `registered` \| `public`). |
| `GET`   | `/reports/search?q=…`             | `reports:read`  | Full-text search across reports the token's owner can read.                               |
| `GET`   | `/reports/:id`                    | `reports:read`  | Report metadata.                                                                          |
| `PATCH` | `/reports/:id`                    | `reports:write` | Update `html`, `title`, or `description`. New HTML appends a revision; the URL is stable. |
| `GET`   | `/reports/:id/revisions`          | `reports:read`  | Revision history (ids, hashes, authorship, timestamps).                                   |
| `GET`   | `/reports/:id/revisions/:rev`     | `reports:read`  | A single revision's content.                                                              |
| `GET`   | `/reports/:id/diff?from=…&to=…`   | `reports:read`  | Line-level diff between two revisions: `{ added, removed, unchanged }`.                   |

Active HTML is sanitized server-side on write, and the public viewer renders
report HTML inside an opaque-origin sandboxed iframe — see
[Security](/security).

## Sharing

| Method | Path                    | Scope          | What it does                                                                  |
| ------ | ----------------------- | -------------- | ----------------------------------------------------------------------------- |
| `GET`  | `/reports/:id/share`    | `reports:read` | Current visibility + link permission.                                         |
| `PUT`  | `/reports/:id/share`    | `sharing`      | Change visibility (`private`, `team`, `registered`, `public`, `domain`) and link permission (`none`, `view`, `comment`, `edit`). |
| `POST` | `/reports/:id/password` | —              | Set a link password (owner only; Enterprise).                                 |
| `DELETE` | `/reports/:id/password` | —            | Clear the link password.                                                      |

The full access model is described in
[Sharing & access control →](/docs/sharing).

## Comments

| Method  | Path                     | Scope            | What it does                                                       |
| ------- | ------------------------ | ---------------- | ------------------------------------------------------------------ |
| `GET`   | `/reports/:id/comments`  | `comments:read`  | List comment threads, including anchors and resolve state.         |
| `POST`  | `/reports/:id/comments`  | `comments:write` | Leave a comment, optionally anchored to a text range or table cell. |
| `GET`   | `/comments/:id/replies`  | `comments:read`  | Replies in a thread.                                               |
| `POST`  | `/comments/:id/replies`  | `comments:write` | Reply to a thread.                                                 |
| `PATCH` | `/comments/:id`          | `comments:write` | Resolve / reopen a thread.                                         |

## Assets

Attach files (images, stylesheets, data) to a report. Limits: 25 MB per
file, 250 MB and 500 files per report.

| Method   | Path                              | Scope           |
| -------- | --------------------------------- | --------------- |
| `GET`    | `/reports/:id/assets`             | `reports:read`  |
| `POST`   | `/reports/:id/assets`             | `reports:write` |
| `DELETE` | `/reports/:id/assets/:assetId`    | `reports:write` |

## Reviews & reviewers

Standing AI reviewers re-check a report when it changes and post their
findings as comments.

| Method | Path                    | Scope           |
| ------ | ----------------------- | --------------- |
| `POST` | `/reports/:id/review`   | `reports:write` |
| `POST` | `/reviews`              | `reports:write` |
| `GET`  | `/reviews/:id`          | `reports:read`  |
| `GET` / `POST` | `/reviewers`    | `routines`      |
| `GET` / `PATCH` / `DELETE` | `/reviewers/:id` | `routines` |

## Routines, skills, connectors

Scheduled regeneration: a routine runs a skill (optionally against
connectors) on a cron and appends the output as a new revision. See
[Routines →](/docs/routines).

| Method | Path                     | Scope         |
| ------ | ------------------------ | ------------- |
| `GET` / `POST` | `/routines`      | `routines`    |
| `GET` / `PATCH` / `DELETE` | `/routines/:id` | `routines` |
| `POST` | `/routines/:id/run`      | `routines`    |
| `GET` / `POST` | `/skills`        | `routines`    |
| `GET` / `PATCH` / `DELETE` | `/skills/:id` | `routines` |
| `GET` / `POST` | `/connectors`    | `connections` |
| `GET` / `PATCH` / `DELETE` | `/connectors/:id` | `connections` |
| `POST` | `/connectors/:id/test`   | `connections` |

## Notifications

Webhook subscriptions on report events (`revision.created`,
`comment.created`, mentions) — deliverable to Slack, Discord, or plain JSON.

| Method | Path                       | Scope      |
| ------ | -------------------------- | ---------- |
| `GET` / `POST` | `/notifications`   | `routines` |
| `GET` / `PATCH` / `DELETE` | `/notifications/:id` | `routines` |
| `POST` | `/notifications/:id/test`  | `routines` |

## Account

| Method | Path             | Scope | What it returns                                  |
| ------ | ---------------- | ----- | ------------------------------------------------ |
| `GET`  | `/me/usage`      | any   | Routine usage + your prepaid credit balance.     |
| `GET`  | `/me/plan-caps`  | any   | Your plan's limits and AI-compute cost rails.    |

## Rate limits

Per-token sliding window, 60 requests/minute by default; higher caps per
plan. `429` responses include `Retry-After`. Details in
[API tokens →](/docs/api-tokens).

## Same surface, other transports

The MCP server at `/api/mcp` exposes this exact surface as tools
(`create_report`, `add_comment`, `run_routine`, …) under the same token —
see [MCP server →](/docs/mcp).