# Quickstart — publish your first report · Comma Docs

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

> Publish an HTML report to Comma in under two minutes: mint a scoped API token, POST the HTML, open the share link.

# Quickstart

Two minutes from zero to a shareable report. You need a Comma account
([sign up free →](/login)) 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_`.

```bash
export COMMA_API_TOKEN="comma_sk_…"
```

## 2. Publish a report

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

```bash
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](/docs/api).

## 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 →](/docs/sharing).

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

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

- Let an agent do this for you: [MCP server →](/docs/mcp) or the
  [Claude Code plugin →](/docs/claude-code-plugin).
- Publish automatically from your pipeline: [CI publishing →](/docs/ci).
- Refresh the report on a schedule: [Routines →](/docs/routines).