API & tokens
Marca's API lives under /api/v1 and is what the snippet, the canvas, and the CLI talk to. This page explains the identifiers and auth so you can reason about access.
Identifiers
- Project token (
proj_…) — the public identifier for a project. It's what goes in the snippet'sdata-projectand in every project-scoped URL. It is not a secret on its own; access is still gated by auth. - Reviewer token — minted when a reviewer signs in through the snippet's auth popup. It scopes that reviewer to a single project so they can read and create comments and tasks, nothing more.
- API key (
sk_live_…) — a project-scoped key used by the CLI and crawler. Create and manage keys from the project's settings. Treat it like a password.
Auth model
Most project routes accept one of three actors:
- a session cookie (dashboard / operator),
- a reviewer token (the embedded widget),
- an API key (CLI / automation).
A token for one project can never read another project's data — cross-project requests resolve to 404. Reviewer tokens are limited to comment and task read/create; operator-only actions (exports, sending to trackers, managing integrations) require a session with member, admin, or owner role.
Common endpoints
All are under /api/v1/projects/{projectToken}:
| Method | Path | Purpose |
|---|---|---|
GET | /comments | List comments for the project. |
POST | /comments | Create a comment (used by the snippet). |
POST | /exports | Promote selected items to tasks and return a brief. Formats: markdown, slack, cursor, claude. |
POST | /send | File selected items as issues. Body: { items, provider: 'github' | 'linear' }. |
GET POST DELETE | /integrations | List, connect/rotate, and disconnect GitHub / Linear. Owner/admin only. |
The snippet bootstrap (/api/v1/snippet/bootstrap) returns auth state and the overlay URL for a given data-project; the snippet calls it on load.
Rate limits & privacy
Unauthenticated routes (signup, snippet bootstrap) are rate-limited per IP. Source IPs are truncated before storage (last IPv4 octet zeroed, IPv6 cut to the first 48 bits) — full IPs are never written to the database or logs.