Docs

One script tag on your site, a link for reviewers, and an agent that closes the threads. Everything below is copy-ready; hostnames are filled in for this deployment.

Two-minute setup

The guided setup does all of this on one screen after you sign in. By hand, it is three steps:

1. Register your site

   In the dashboard, add the origin your pages are served from, for example https://www.example.com. You get the snippet.

2. Paste the snippet

   Before </body> on every page you want reviewed. Nothing else changes on your site.

3. Share a review link

   Mint one on the site page and send the URL. Reviewers pick a name once and start commenting. No accounts.

<script src="{API_BASE}/widget/v1/widget.js" data-site-key="pk_…" data-review="on" defer></script>

The site page always shows this with your real key filled in. The key is public by design: the API only accepts it from your site's origin.

What reviewers see

A reviewer opens any page of your site through the review link, types a display name once, and the page is live for comments. Try it on the demo first.

Comments re-anchor by content when a paragraph moves between deploys. When the text is gone, the thread lands in an orphaned tray, still readable and closable.

Scripts and CI: the API token

Agents connect over MCP with a browser sign-in (next section) and never see a token. For a script, a CI job or a harness that cannot sign in, mint an API token under Tokens & billing and send it as Authorization: Bearer ak_…. It acts as you, across every site in your account, with no cookie and no Origin header.

Register a site and get its snippet

curl -s -X POST {API_BASE}/sites \
  -H "Authorization: Bearer ak_…" -H "Content-Type: application/json" \
  -d '{"name": "Acme", "origin": "https://www.acme.example"}'

The answer carries id, the raw site_key and the ready-made snippet. The snippet is readable again any time with GET /sites/{id}.

Mint a review link

curl -s -X POST {API_BASE}/sites/<site_id>/links \
  -H "Authorization: Bearer ak_…" -H "Content-Type: application/json" \
  -d '{"label": "design partners"}'

You get share_url and the raw code, once. Revoke with DELETE /sites/{id}/links/{link_id}.

Work the threads

# open threads on the home page ("index"); other pages use their path as the slug
curl -s "{API_BASE}/api/threads?page=index" \
  -H "Authorization: Bearer ak_…" -H "X-Site-Id: <site_id>"

# reply, then close with the commit that shipped the fix
curl -s -X POST {API_BASE}/api/threads/<thread_id>/comments \
  -H "Authorization: Bearer ak_…" -H "X-Site-Id: <site_id>" \
  -H "Content-Type: application/json" -d '{"body": "Fixed in a1b2c3"}'
curl -s -X PATCH {API_BASE}/api/threads/<thread_id> \
  -H "Authorization: Bearer ak_…" -H "X-Site-Id: <site_id>" \
  -H "Content-Type: application/json" -d '{"status": "closed", "site_version": "a1b2c3"}'

Each thread carries page_slug, anchor and context_snapshot, the exact text the reviewer saw, which is how an agent finds the spot in the source.

Connect an agent over MCP

The API hosts an MCP server at {API_BASE}/mcp (streamable HTTP). Point your client at the URL: it registers itself and opens your browser to sign in the first time, then keeps a refreshable credential of its own. No token is copied anywhere.

• Claude Code
• Cursor
• Claude Desktop

claude mcp add --transport http comments {API_BASE}/mcp

{
  "mcpServers": {
    "comments": {
      "url": "{API_BASE}/mcp"
    }
  }
}

{
  "mcpServers": {
    "comments": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "{API_BASE}/mcp"]
    }
  }
}

How the sign-in works

The API is an OAuth resource server for the central sign-in service. It serves {API_BASE}/.well-known/oauth-protected-resource/mcp, answers an unauthenticated MCP call with a WWW-Authenticate challenge that points there, and accepts the issuer's RS256 tokens for its own audience next to ak_… tokens on every owner route. Your first visit needs a verified email in the grant; after that the stable subject alone is enough. The same email as your magic-link account lands you in the same account.

Tools

The triage(site_id) prompt walks the open threads: find each element in the source by its page slug and captured text, fix it, reply with one line, close with the deployed commit, and leave what it cannot resolve in in review with a reason.

Snippet options

The origin must match

The widget's first call sends the page's Origin; the API answers only for the site's origin or one of its extra allowed origins. An origin is scheme, host and port with no path: https://www.example.com and https://example.com are two different sites. Add a staging host or a local dev server (http://localhost:3000) under Allowed origins on the site page.

Review links

Reviewers do not have accounts. They join through a link you mint on the site page, labelled for the cohort ("design partners", "client round 2"), optionally with an expiry.

https://your-site/?review=rv_…

• The code works on any page of the site, as ?review=… or #review=…, so you can send reviewers straight to the page in question. The widget removes it from the address bar and remembers the reviewer in that browser.
• Review link for me mints a link labelled owner so you comment through the same path reviewers use.
• Revoke a link and every reviewer who joined through it is out on their next request; their comments stay. Revoke one reviewer from the reviewers table to remove a single person.
• An expired link behaves like a revoked one. A locked-out reviewer sees a quiet "ask the site owner for a review link" note; a fresh link lets them back in.

Clearing, resetting, rebuilding

• Delete a thread from the site page or with DELETE /api/threads/{id}. Owners only; reviewers close threads and delete their own comments.
• Clear in bulk with DELETE /sites/{id}/threads: filter by page, status, orphaned=true or before=<datetime>, or send no filter to reset the site. Keys, review links and reviewers stay, so pages and reviewers keep working.
• Auto-clear a playground or demo site by setting delete threads older than N days on its site page; the retention job runs a few times a day.
• Export everything as JSON from the site page or GET /sites/{id}/export before a rebuild.
• After a rebuild, the widget re-anchors each thread: same text means a moved paragraph and is re-attached; edited text is matched on the captured snapshot; anything else is reported as orphaned and shown in the reviewers' tray. The site page lists orphans, and Close all orphans or clear orphaned finishes the round.
• Switch the widget off at the top of the site page to pause; rotate the site key to cut off pages that still carry an old snippet; delete the site to remove everything, which cannot be undone.

HTTP API reference

Base URL {API_BASE}. Owner routes accept the dashboard's session cookie, Authorization: Bearer ak_…, or a bearer from the central sign-in. Reviewer routes take Authorization: Bearer rt_… plus X-Site-Key and a matching Origin. Thread routes accept either; an owner names the site with X-Site-Id. Raw keys, codes and tokens are returned once. The interactive OpenAPI reference is at the API's /docs.

Limits: 4,000 characters per comment, 500 threads per page, 200 comments per thread, 10 extra origins per site. Rate limits answer 429 with a Retry-After header. A resource from another account is a 404, never a 403.