Comma

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; 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.

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 →.

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 →.

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 Usage against your plan's limits.
GET /me/plan-caps any Your plan's caps (routine cadence, AI run budget).

Rate limits

Per-token sliding window, 60 requests/minute by default; higher caps per plan. 429 responses include Retry-After. Details in 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 →.