Comma

Quickstart

Two minutes from zero to a shareable report. You need a Comma account (sign up free →) and a terminal.

1. Mint an API token

Go to Settings → API tokens → New token in the app. Pick the scopes the token should carry — for publishing, reports:write is enough. Copy the token; it's shown once and starts with comma_sk_.

export COMMA_API_TOKEN="comma_sk_…"

2. Publish a report

POST /api/v1/reports with the HTML in the body:

curl -X POST https://commareports.com/api/v1/reports \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Hello from the API",
    "html": "<h1>It works</h1><p>This report was published with one curl.</p>"
  }'

The response includes the report id and its URL. HTML up to 5 MB is accepted; attach larger assets (images, CSS, JS) separately — see the REST API reference.

3. Open and share it

Open the returned URL. From the share dialog you control who can see the report — private, your team, any signed-in user, or anyone with the link — and whether link-holders can view, comment, or edit. Details in Sharing & access control →.

4. Update it later

Reports are living documents. PATCH /api/v1/reports/:id with new html appends a revision — the URL stays stable, the history is kept, and reviewers can diff any two revisions.

curl -X PATCH https://commareports.com/api/v1/reports/REPORT_ID \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "html": "<h1>v2</h1><p>Same URL, new revision.</p>" }'

Where to next