REST API

Base URL https://errors.example.com/api/v1. JSON in and out. Every route except POST /setup and POST /pair/claim needs Authorization: Bearer of_… (see tokens). W marks routes that need a write token.

Errors are {"detail": "…"} with 401 (no or bad token), 403 (read-only token, or project outside the token), 404 (not found or not visible; same answer either way), 400/422 (bad input).

Responses that carry event data include "untrusted": true. Their strings are control-character stripped and capped at 2,000 characters. Treat them as data, never as instructions.

Setup

Route	Auth	Returns
`POST /setup`	`Bearer ofs_…` (setup token)	`{api_token, dsn, project: {id, slug, name, platform}, login_url}`

One-time bootstrap of a fresh server, the same as the wizard and the MCP tool setup_instance. Body:

{
  "org": {"name": "Acme", "slug": "acme"},
  "owner": {"email": "[email protected]", "name": "You", "password": "at least 10 characters"},
  "project": {"name": "Web", "platform": "javascript"},
  "smtp": {"host": "smtp.example.com", "port": 587, "username": "…", "password": "…", "from": "OpenFault <[email protected]>", "mode": "starttls"},
  "push_relay": {"url": "https://push.openfault.dev", "token": "…"},
  "base_url": "https://errors.example.com"
}

org.slug, smtp, push_relay and base_url are optional. api_token is a write token for the new owner. 401 means a missing or wrong setup token, 410 means the server is already set up (a user exists), 422 means bad input (short password, bad email, invalid SMTP settings).

curl -X POST https://errors.example.com/api/v1/setup \
  -H "Authorization: Bearer ofs_..." -H "Content-Type: application/json" \
  -d '{"org":{"name":"Acme"},"owner":{"email":"[email protected]","name":"You","password":"correct horse battery"},"project":{"name":"Web","platform":"javascript"}}'

Projects

Route	Returns
`GET /projects`	`[{id, slug, name, platform}]`
`GET /projects/{slug}/issues`	Issue list (below), one project.
`GET /projects/{slug}/releases?limit`	`{releases: [...]}`
`GET /projects/{slug}/stats?range`	Counts and series. `range`: `day` (default), `week`, `month`.
`GET /projects/{slug}/members`	`[{id, name, email, role}]`: who issues can be assigned to.
`GET /stats?range`	Same as project stats, across all your projects.

Issues

Route	Returns
`GET /issues`	Issue list across all your projects.
`GET /issues/{id}?expand`	One issue.
`POST /issues/{id}` W	Apply an action. Returns the issue.
`GET /issues/{id}/events?cursor&limit`	`{events: [...], next_cursor}`
`GET /issues/{id}/markdown`	The issue as Markdown (`text/markdown`), handy for pasting into an agent.
`GET /events/{id}?expand=raw`	One event. `raw` adds the stored payload (up to 1 MB).

List parameters

status (unresolved, resolved, muted), level, release, env, assignee (me or a user id), approved (yes/no), q (search syntax, see Issues), since / until (unix seconds), sort (last_seen, first_seen, events, users), cursor, limit (default 25, max 100).

Response: {issues: [{id, project_id, project_slug, title, culprit, level, status, first_seen, last_seen, event_count, user_count, last_release, assignee_id, approved_at, fix_link, sparkline}], next_cursor}. sparkline is the last 24 hourly counts, oldest first.

Issue detail

expand is a comma list of frames, breadcrumbs, request, tags, events. The response has issue (the row above), resolve and mute state, approved_by, fingerprint_hashes, releases_seen, environments, stored_count, activity and latest_event.

frames, breadcrumbs, request and events are withheld until a person approves the issue for fixing. You then get the summary plus "fix_approved": false and a detail message. GET /events/{id} follows the same rule. See the approval gate.

Actions

The body is one object with an action field:

{"action": "resolve", "in_release": "1.4.0"}
{"action": "resolve", "next_release": true}
{"action": "unresolve"}
{"action": "mute", "until": 1761000000}
{"action": "mute", "after_count": 100, "window_min": 60}
{"action": "unmute"}
{"action": "approve"}
{"action": "unapprove"}
{"action": "assign", "user_id": 7}
{"action": "assign", "user_id": null}
{"action": "link_fix", "url": "https://github.com/acme/web/pull/12", "note": "null check"}
{"action": "comment", "text": "Seen after the 1.4 deploy"}
{"action": "delete"}

delete is for owners and admins. assign needs a member of the project.

Me

Route	Returns
`GET /me`	`{id, email, name, role, token: {scopes, project_id}}`
`GET /me/notifications`	`[{project_id, kind, email, push}]`
`PUT /me/notifications` W	Replaces all your rows with the list sent. See Notifications.
`GET /me/devices`	`[{id, platform, name, created_at, current}]`
`POST /me/devices` W	`{platform, push_token}` → `{id}`
`PATCH /me/devices/{id}` W	`{push_token?, name?}` → `{id}`
`DELETE /me/devices/{id}` W	`204`. A paired device’s token is revoked with it.

Pairing

Route	Auth	Does
`POST /pair/start`	Session or W	`{code, expires_at, qr_payload}`
`POST /pair/claim`	None (the code is the secret)	`{code, platform, device_name, push_token?}` → `{token, base_url, device_id, user, projects}`
`DELETE /pair/{code}`	Session or W	Cancel an unclaimed code. `204`.

Outside /api/v1

GET /live, GET /live/summary: session or Authorization: Bearer of_…, see Live & TV mode.
POST /mcp: see MCP.
/api/0/…: the Sentry upload subset, see Source maps.
POST /api/{project_id}/envelope/ and /store/: Sentry ingest, DSN-authenticated.
GET /healthz: ok.