# API Reference

Base URL: `https://app.bugtape.ai`

All endpoints are prefixed with `/v1/`.

## Authentication

The API uses these authentication modes:

| Mode | Header(s) | Used for |
|------|-----------|----------|
| `Bearer agent PAT` | `Authorization: Bearer bt_pat_…` | Explicit agent actions; work and evidence require current project grants as stated below |
| `none` | — | Public unauthenticated endpoints (register, login, reset, etc.) |
| `X-BugTape-Key` | `X-BugTape-Key: bt_live_*` | SDK ingestion (`POST /v1/ingest`, `POST /v1/ingest/presence`, `POST /v1/ingest/ai-summary`) |
| `Bearer JWT` | `Authorization: Bearer <token>` | User-scoped endpoints that do not need an org (e.g. `/v1/auth/me`) |
| `Bearer JWT + X-BugTape-Org` | `Authorization: Bearer <token>` + `X-BugTape-Org: <uuid>` | All workspace/management endpoints |
| `Bearer JWT + Superadmin` | `Authorization: Bearer <token>` | Endpoints under `/v1/admin/*` — the caller's email must be in the `ADMIN_EMAILS` env allowlist |

JWT access tokens last one hour; refresh tokens last 30 days. Human requests check the current active account, email and session revision. Status, email and password changes advance the revision and retire previously issued access/refresh tokens; reactivation requires a new login. Profile edits do not retire sessions. These guarantees start with migration048. Version2 tokens with no revision represent revision0. A rejected session returns 401; an unavailable account lookup returns 503 `AUTH_UNAVAILABLE` so clients can retry. Agent PATs keep their separate revocation/expiry lifecycle.

Exchange a refresh token via `POST /v1/auth/refresh` for a fresh access token.

See [Authentication](./authentication.md) for details on token lifetimes and key formats.

## Agent token management

Use a human JWT and `X-BugTape-Org`. `GET /v1/org/agent-pats` lists token
metadata, project grants and an opaque `accessRevision`; it never returns secrets.
`POST /v1/org/agent-pats` creates a token and returns its secret once.
`PATCH /v1/org/agent-pats/:id` changes `scopes`, `expiresAt` and/or `projectGrants`.
Send the latest `accessRevision` as `expectedRevision` to reject concurrent edits.
A mismatch returns 409 `AGENT_ACCESS_CHANGED`; reload, review and resubmit.
Legacy callers may omit this field, but then have no stale-edit protection.

Only admins/managers can edit access; a manager cannot manage an admin-owned token.
An expired token returns 409 `AGENT_PAT_EXPIRED` and requires replacement.
Revoked tokens cannot be edited. Expiry must be in the future within 365 days.
A supplied `projectGrants` array replaces the selected work grants; an empty array
revokes all work grants. Explicit grant expiry cannot exceed token expiry.
Omitting `projectGrants` preserves existing grants, capped by any shorter token
expiry. Project grants affect work claims/evidence/verification/symbol publishing; they do not narrow
legacy workspace actions. `DELETE /v1/org/agent-pats/:id` revokes the credential.

## Agent sign-in (OAuth 2.1)

Agents and chatbots can get an agent token without anyone copying it. Every grant ends in an ordinary agent token (above): it is listed on the Team page and revoked there. Access tokens keep their 12-character prefix across refreshes.

| Endpoint | Purpose |
|---|---|
| `GET /.well-known/oauth-protected-resource/mcp` | Resource metadata (RFC 9728): resource `https://app.bugtape.ai/mcp`, authorization server `https://app.bugtape.ai` |
| `GET /.well-known/oauth-authorization-server` | Server metadata (RFC 8414): PKCE `S256`, `token_endpoint_auth_methods_supported: ["none"]`, `client_id_metadata_document_supported: true` |
| `GET /oauth/authorize` | Authorization code + PKCE. `client_id` is a Client ID Metadata Document URL (not an IP address) or a registered id. Sends the person to `/console/connect?request=<id>` |
| `POST /oauth/register` | Dynamic client registration (RFC 7591), public clients only |
| `POST /oauth/device_authorization` | Device code (RFC 8628), for BugTape's own CLI only: `client_id=bugtape-cli`, optional `name`, `agent_kind`, `scope`. Any other client gets `unauthorized_client` |
| `POST /oauth/token` | `authorization_code` (a replayed code revokes what it minted), `refresh_token` (rotates; one retry inside 60 s is honoured, anything else that re-uses or replaces a token revokes the grant, so refresh one at a time), `urn:ietf:params:oauth:grant-type:device_code`. Form-encoded or JSON |
| `POST /oauth/revoke` | Revokes a refresh token's grant, or an OAuth-issued access token |

`POST /mcp` without a valid agent token answers `401` with `WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp"`. Pasted `bt_pat_` tokens work as before.

The consent page uses human-JWT routes: `GET /v1/oauth/requests/:id`, `GET /v1/oauth/device/:userCode`, `POST /v1/oauth/requests/:id/approve` (`orgId`, `access: fix|read`, `days: 30|90|180|365`, `fileIssues`, `setupCapture`) and `POST /v1/oauth/requests/:id/deny`. Agent tokens and support sessions get 403.

### `POST /v1/projects/capture-setup`

Human JWT, or an agent token with `setup_capture`. Body: `platform` (`web`, `node`, `python`, `workers`, `server`, `ios`), optional `projectId` or `projectName`, `service`, `release`, `check`. Finds or creates the project (on a plan that allows one project, uses it and returns a `note`), makes a capture key labelled for the agent, and returns `project`, `captureKey` (secret once), `ingestUrl`, `steps` (install steps with the release wired) and, with `check: true`, the receipt of one `SetupCheckError: BugTape is connected` report. Used by `bugtape init` and the MCP tool `setup_capture`.

## Agent claims and runner verification

These endpoints use a current **agent PAT**, not a capture key or human JWT.
They recheck the active account, workspace membership, token scopes, project grant,
canonical issue and lease. The complete request fields and signing byte format are
in [Runner verification](./runner-verification.md). No private server import is required.

All paths below start with `/v1/agent-work`. POST bodies are strict JSON objects.
Every work command has UUID `commandId`, `projectId` and `issueId`. Lease commands
also require `claimId`, `generation` and `fencingToken`; the latter two are positive
decimal **strings**. Preserve the exact command after an uncertain response and retry
it with the same ID. Changing input under that ID is a conflict.

| Method and path | Required PAT action | Additional input / behavior |
|---|---|---|
| POST `/claims` | `claim_issue` | Optional `ttlSeconds`:60–900, default300. Returns the current fenced lease. |
| POST `/claims/renew` | `claim_issue` | Lease fields; optional TTL. Expired or stale leases cannot be renewed. |
| POST `/claims/release` | `claim_issue` | Lease fields. Release unfinished work. |
| POST `/claims/complete` | `claim_issue` | Lease fields plus `receiptId`. Closes work; does not verify the issue. |
| GET `/claims` | `claim_issue` or `request_evidence` | Query `projectId`, `issueId`; returns `{claim}`. |
| POST `/verification/challenges` | `submit_verification` | Lease fields. Same PAT must submit the signed attempt. |
| POST `/verification/receipts` | `submit_verification` | Exact measured submission and optional runner proof. Unsigned attempts remain pending. |
| GET `/verification/receipts/:receiptId` | `read_verification` | Query `projectId`, `issueId`; inspect status, trust and current applicability. |
| GET `/verification/receipts/:receiptId/evidence` | `request_evidence` | Same query; metadata only, `contentAvailable:false`. |
| POST `/verification/promote` | `submit_verification` plus current claim authority | Live lease fields, exact target builds and current receipt IDs covering observed applications/runtimes; successful promotion also completes the claim. |

A valid signature is not sufficient for promotion. The server also checks registered
scope, actual ready artifacts, test outcomes and current authority. A receipt can
remain historical after recurrence, regrouping or revoked evidence. Legacy
`verified_fixed` labels can be unproven. GET `/v1/bugs/:id` includes nullable
`active_verification_promotion_id`; use receipt reads to check current applicability.

### Human enrollment and measured evidence

Runner/device enrollment is **human organization admin only**, with Bearer JWT and
`X-BugTape-Org`. Paths start with `/v1/agent-work/verification`:

| Method and path | Input |
|---|---|
| POST `/runners` | `commandId`, `projectId`, `name`, Ed25519 `publicKeyPem`, `trustLevel` (`ci` or `device_lab`), `allowedRuntimes`. Never send a private key. |
| POST `/devices` | `commandId`, `projectId`, `name`, `runnerId`, `applicationId`, `installationId`, `runtime`, `deviceIdentifierSha256`, `osVersion`; physical iOS requires explicit `physicalDeviceConfirmed:true`. |
| GET `/enrollment` | Query `projectId`; public enrollment metadata only. |
| POST `/runners/revoke` | `commandId`, `projectId`, `runnerId`. |
| POST `/devices/revoke` | `commandId`, `projectId`, `deviceId`. |

Register the tested build through the human manager/admin application registry:
POST `/v1/applications/projects/:projectId/:applicationId/builds` with `requestId`,
`sourceRevision` and `artifactSha256`. Copy the returned ID; never use a failed build's
identity for repaired code.

Check GET `/v1/evidence/capabilities` before attempting evidence transfer. A PAT needs
`create_bug` and a current project grant to reserve/upload a measured log; verification
scope alone does not grant upload access. Reserve with POST
`/v1/evidence/projects/:projectId/artifacts`, upload exact bytes with PUT
`/v1/evidence/projects/:projectId/artifacts/:artifactId/content`, and inspect ready
metadata with GET `/v1/evidence/projects/:projectId/artifacts/:artifactId` using
`get_repro_context` and a grant. The guide lists required fields and hash checks.
Use repaired application/build/installation IDs. Normally omit `occurrenceId` from
the reservation; the failed occurrence has the failed build scope. The verification
receipt links that failure separately through `failedOccurrenceId`.

The `publish_symbols` PAT action is separate from `create_bug`. Local symbol admission
requires a current exact project grant plus an existing application/build scope. Capture
keys, ordinary PATs and human sessions cannot use that upload path. Hosted symbol
admission remains disabled until G9. A stored symbol artifact is not usable until the
bounded worker records its own exact UUID and architecture match.

For a locally enabled environment, publish with:

`BUGTAPE_PAT=... npm --workspace @bugtape/api run symbols:publish -- --endpoint https://host --project UUID --application UUID --build UUID --file PATH`

The CLI checks advertised capability and the exact ready receipt. It never supplies UUID
or architecture; the isolated worker observes and records those values.

## Rate limits

| Scope | Limit | Window |
|-------|-------|--------|
| General API | 200 requests | 60 seconds per IP |
| Ingestion | 100 requests | 60 seconds per IP |
| Auth (login/register/reset) | 10 requests | 60 seconds per IP |

Rate-limited responses return `429` with a `Retry-After` header (seconds, the same value as `retryAfter`):

```json
{
  "error": "Too many requests",
  "retryAfter": 45
}
```

## Payload size limit

`POST /v1/ingest` accepts JSON up to **10 MB** (10 × 1024 × 1024 bytes) after decompression. `gzip`, `deflate` and `br` inflate only up to that same limit. A larger body is `413`:

```json
{ "error": "request entity too large", "requestId": "req_abc123" }
```

On `POST /v1/ingest` the rate limits and the `X-BugTape-Key` check run before the body is read. A rate-limited call is `429` and a missing or unknown key is `401`, even when the body is too large or is not valid JSON. The server reads and discards the rest of a rejected body (at most 20 MB or 10 seconds), so the client can read the status.

Account JSON, including `POST /v1/auth/login`, is 64 KB. The marketing beacon `POST /v1/growth/hit` is 16 KB of text. OAuth register, device, token and revoke bodies are 32 KB. Evidence reservation JSON is 16 KB; the upload itself is a separate stream. Owner Lighthouse import (`POST /v1/growth/snapshots/import`) is 8 MB. Agent-work JSON, including failure packs, is 10 MB after the agent session check. Other console JSON is 64 KB.

## Common error envelope

Every error response is JSON and always contains at least an `error` field. When Express 5's global error handler catches an unhandled exception it also attaches a `requestId` so you can correlate logs:

```json
{
  "error": "Internal server error",
  "requestId": "req_abc123"
}
```

Malformed JSON bodies return:

```json
{ "error": "Invalid JSON in request body" }
```

Plan-limit violations return HTTP `402`:

```json
{
  "error": "Plan limit reached",
  "limit": 100,
  "current": 100,
  "plan": "free",
  "upgradeUrl": "/console/#settings"
}
```

---

## Health

Fly liveness probes `GET /v1/health`. That 200 is **not** a ship signal.
Release checks use `GET /v1/health/deep` (see repo `docs/reliability.md` and
`DEPLOY_FLY.md`). `jobs.status === 'degraded'` can still ride on HTTP 200;
refuse ship unless the debt is the owned historical set.

There is no published OpenAPI document. `@bugtape/contracts` plus
`packages/api/tests/integration/contract-drift.test.ts` are the handler-drift
tripwire.

### `GET /v1/health`

Verifies the API process and a cheap PostgreSQL ping. Fly uses this as liveness.

**Auth**: `none`

**Success response (200):**

```json
{
  "status": "ok",
  "service": "bugtape-api",
  "timestamp": "2026-04-17T00:00:00.000Z"
}
```

**Degraded (503):**

```json
{
  "status": "degraded",
  "service": "bugtape-api",
  "error": "Database unreachable",
  "timestamp": "2026-04-17T00:00:00.000Z"
}
```

### `GET /v1/health/deep`

Public body is `{ status, timestamp }` only (`ok` or `degraded`). HTTP **200**
when `db` + migrations are ok; **503** when those critical checks fail.

With `X-BugTape-Health-Token` (or `Authorization: Bearer`) set to
`HEALTH_DEEP_TOKEN`, or a current superadmin session, the
body also includes `checks`: `db`, `migrations`, `email`, `ai`, `jobs`
(pg-boss DLQ / failed-consumer depths), `redis`. Names, booleans and counts
only — no secrets. A wrong token still gets the public body (not 401). `jobs`
and `redis` are informational on the HTTP status and still matter for release.

**Auth**: `none` for status. Detail: health token, or a superadmin session.

---

## Auth

All auth endpoints live under `/v1/auth/*` and share the auth rate limiter (10 req/min/IP).

### `POST /v1/auth/register`

Open self-serve signup. Creates a user, org, default project, and API key. Duplicate email returns `409`.

**Auth**: `none`

**Request body:**

```json
{
  "email": "user@example.com",
  "password": "at-least-8-chars",
  "name": "Full Name",
  "orgName": "Workspace Name",
  "signupCode": "FRIENDS-ABC234"
}
```

`signupCode` is optional: an invite code from a friends-and-family link. The workspace starts with the code's prepaid credits (10,000 by default), which gives it Pro limits until they run out. The credits are granted in the same transaction that creates the account.

`attribution` is optional: `{ sid, jvSid, ref, path, utm }`, the landing visit the signup came from (the console sends what the landing put on the sign-up link). Each field is checked on its own; a bad value is dropped, never a `400`. `sid` is the page counter's visit id (`?bt_s=`). `jvSid` is the hub counter's visit id (`?jv_s=`, `[A-Za-z0-9_-]{8,40}`). When `JV_PULSE_IMPORT_TOKEN` is set, the server sends one anonymous signup count to the hub counter after the account is created: a random id, the site, the time and `jvSid` (or null). It never sends the email, name, user id or workspace id, and it never delays or fails the signup.

**Response (201):** user, org, project, apiKey, accessToken, refreshToken, `signupCredits` (credits the invite code added; `0` without one).

**Error codes:** `400` Validation failed · `400 SIGNUP_CODE_INVALID` the invite code is unknown, switched off, expired or used up (`details.reason`: `unknown` | `disabled` | `expired` | `used_up`); no account is created · `409` Email already registered.

### `GET /v1/auth/signup-codes/:code`

Check an invite code before signup. Case-insensitive. Shares the strict auth limit (10 req/min/IP).

**Auth**: `none`

**Success (200):** `{ "valid": true, "code": "FRIENDS-ABC234", "credits": 10000 }`

**Errors:** `400 SIGNUP_CODE_INVALID` (same reasons as register).

### `GET /v1/auth/approval/:token`

Validate an approval link token (issued before signup opened) without consuming it. Used by the signup form to pre-fill fields.

**Auth**: `none`

**Path params:** `token` — hex approval token from the email link.

**Success (200):**

```json
{
  "email": "user@example.com",
  "name": "Full Name",
  "orgName": "Workspace Name"
}
```

**Error codes:** `400` Invalid or expired approval link.

### `POST /v1/auth/complete-signup`

Consume an approval link token (issued before signup opened) and materialize the user, organization, default project, first API key, and tokens. Marks the new user as email-verified.

**Auth**: `none`

**Request body:**

```json
{
  "token": "<approval token>",
  "name": "Full Name",
  "password": "at-least-8-chars"
}
```

**Success (201):**

```json
{
  "user":   { "id": "uuid", "email": "user@example.com", "name": "Full Name" },
  "org":    { "id": "uuid", "name": "Workspace Name", "slug": "workspace-name" },
  "project":{ "id": "uuid" },
  "apiKey": "bt_live_...",
  "accessToken": "eyJ...",
  "refreshToken": "eyJ..."
}
```

**Error codes:** `400` Validation failed / Invalid or expired approval link · `409` Email already registered.

### `POST /v1/auth/login`

Authenticate with email + password.

**Auth**: `none`

**Request body:**

```json
{ "email": "user@example.com", "password": "..." }
```

**Success (200):**

```json
{
  "user": { "id": "uuid", "email": "user@example.com", "name": "Full Name" },
  "org":  { "id": "uuid", "name": "Workspace Name" },
  "accessToken": "eyJ...",
  "refreshToken": "eyJ..."
}
```

**Error codes:**

| Status | Body | Cause |
|--------|------|-------|
| 400 | `{ "error": "Validation failed" }` | Missing/invalid email or password |
| 401 | `{ "error": "Invalid credentials" }` | Unknown email or wrong password |
| 403 | `{ "error": "Invitation pending — check your email to set a password.", "code": "INVITE_PENDING" }` | User record exists but has no password yet (invite flow) |
| 403 | `{ "error": "Verify your email before signing in", "code": "EMAIL_UNVERIFIED", "maskedEmail": "us**@example.com" }` | Email not verified |

### Invitation account setup

`POST /v1/auth/invitations/inspect` accepts `{token}` and returns `{orgName,email,expiresAt}` without consuming the token. `POST /v1/auth/invitations/accept` accepts `{token,email,newPassword}` and returns `{success,orgId,orgName,message}`. The password needs at least8characters. Both are public bearer-link operations. Invalid, expired, revoked or reused credentials return400 `INVITATION_INVALID`. Current membership is checked under lock. Acceptance does not overwrite an active account password.

The emailed link is `/console/invite#token=…`. The page removes the fragment from history and keeps it only in memory; after reload, reopen the email link. Authentication pages are excluded from console self-report recording.

`POST /v1/auth/api-key-session` is retired and always returns 410 `CAPTURE_KEY_SESSION_RETIRED`. Public browser capture keys only authorize capture. Agents use scoped PATs; human auth routes, including `switch-org`, reject PATs. `GET /v1/auth/agent-context` returns only the PAT workspace `{orgId,orgName,role,scopes}` and rejects a mismatched workspace header. MCP `get_current_org` uses this scoped endpoint.

### `POST /v1/auth/refresh`

Exchange a current version2 refresh token for a fresh access token + refresh token. Older sessions require one fresh sign-in following the capture-key session retirement. Refresh tokens cannot authenticate bearer routes.

**Auth**: `none` (the refresh token itself is the credential)

**Request body:**

```json
{ "refreshToken": "eyJ..." }
```

**Success (200):**

```json
{ "accessToken": "eyJ...", "refreshToken": "eyJ..." }
```

**Error codes:** `400` Refresh token required · `401` Invalid, expired or retired session, inactive/missing account, or malformed token · `503` Authentication lookup temporarily unavailable.

### `GET /v1/auth/me`

Return the authenticated user, all org memberships, and a `isSuperAdmin` flag.

**Auth**: `Bearer JWT`

**Success (200):**

```json
{
  "id": "uuid",
  "email": "user@example.com",
  "name": "Full Name",
  "avatar_url": null,
  "email_verified": true,
  "orgs": [
    { "orgId": "uuid", "role": "admin", "orgName": "Workspace Name" }
  ],
  "isSuperAdmin": false
}
```

**Error codes:** `401` Missing or invalid token · `404` User not found.

### `POST /v1/auth/forgot-password`

Request a password-reset email. Always returns `200` to prevent email enumeration. Sends the reset link asynchronously; in non-production, the response also includes `token` for testing.

**Auth**: `none`

**Request body:**

```json
{ "email": "user@example.com" }
```

**Success (200):**

```json
{ "success": true, "message": "If that email exists, a reset link has been sent." }
```

**Error codes:** `400` Email is required.

### `POST /v1/auth/reset-password`

Consume a password-reset token atomically and set a new password for an active account. Pending invitations and deactivated accounts cannot use recovery to activate themselves. New teammates use invitation acceptance.

**Auth**: `none`

**Request body:**

```json
{
  "token": "<reset token>",
  "email": "user@example.com",
  "newPassword": "at-least-8-chars"
}
```

**Success (200):**

```json
{ "success": true, "message": "Password has been reset. You can now sign in." }
```

**Error codes:** `400` Validation failed / Invalid or expired reset token.

### `POST /v1/auth/send-verification`

Issue a fresh email-verification token for the currently authenticated user and send the verification email.

**Auth**: `Bearer JWT`

**Request body:** *(none)*

**Success (200):**

```json
{ "success": true, "message": "Verification email sent", "maskedEmail": "us**@example.com" }
```

Or, if already verified:

```json
{ "success": true, "message": "Email already verified" }
```

**Error codes:** `404` User not found · `503` `Email delivery is not configured or failed. Contact support.`

### `POST /v1/auth/resend-verification`

Public variant of `send-verification`. Always returns `200` with a generic message, even for unknown / already-verified addresses, to prevent enumeration.

**Auth**: `none`

**Request body:**

```json
{ "email": "user@example.com" }
```

**Success (200):**

```json
{
  "success": true,
  "message": "If that account exists, a verification email has been sent.",
  "maskedEmail": "us**@example.com"
}
```

**Error codes:** `400` Validation failed · `503` Email delivery failed.

### `POST /v1/auth/verify-email`

Consume an email-verification token and mark the owning user as verified.

**Auth**: `none`

**Request body:**

```json
{ "token": "<verification token>" }
```

**Success (200):**

```json
{ "success": true }
```

**Error codes:** `400` Token is required · `400` Invalid or expired verification token.

### `GET /v1/auth/whats-new`

Summarize activity since the user's `last_login` for the currently-scoped org. Used by the "What's new" popover in the console.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):**

```json
{
  "items": [
    { "type": "new_bug", "id": "uuid", "title": "...", "severity": "high", "ts": "ISO 8601" },
    { "type": "regression", "id": "uuid", "title": "...", "severity": "critical", "ts": "ISO 8601" },
    { "type": "resolved", "id": "uuid", "title": "...", "severity": "low", "ts": "ISO 8601" }
  ],
  "since": "ISO 8601",
  "counts": { "newBugs": 3, "regressions": 1, "resolved": 5 }
}
```

If no org header is supplied, returns `{ "items": [] }`. On first login (no prior `last_login`), returns `{ "items": [], "firstLogin": true }`.

---

## Ingestion

### `POST /v1/ingest`

Submit a bug report. This is the primary SDK integration endpoint.

**Auth**: `X-BugTape-Key`
**Rate limit**: 100/min per IP

Legacy screenshot/audio/encrypted fields are not proof of retrievable media storage. For current capture IDs, payload limits and storage boundaries, use the [ingest contract](./ingest-schema.md).

#### Request headers

```http
Content-Type: application/json
X-BugTape-Key: bt_live_your_key_here
```

#### Request body

```typescript
{
  // Required
  title: string,                // 1-500 characters

  // Optional
  description?: string,         // 0-10,000 characters
  severity?: "critical" | "high" | "medium" | "low",  // default: "medium"
  url?: string,                 // 0-2,000 characters
  userAgent?: string,           // max 500 characters
  viewport?: string,            // max 50 characters, e.g. "1920x1080"
  events?: Event[],             // max 1,000 events
  screenshot?: any,             // base64 or JSON object
  audio?: any,                  // base64 or JSON object
  aiSummary?: any,              // client-side AI summary
  encrypted?: object,           // unsupported: not a retrievable encrypted-artifact path
  reporterEmail?: string,       // valid email
  reporterId?: string,          // max 200 chars — app-specific reporter id
  sessionId?: string,           // max 200 chars
  userId?: string,              // max 200 chars
  release?: string,             // max 200 chars (app version on mobile)
  environment?: string,         // max 100 chars
  platform?: string,            // web | ios | android | react-native | flutter | server | other (inferred from userAgent when omitted)
  device?: string,              // max 120 chars, e.g. "iPhone15,3" → metadata.device
  osVersion?: string,           // max 60 chars, e.g. "17.4.1" → metadata.osVersion
  metadata?: object             // arbitrary per-occurrence metadata
}
```

#### Event schema

```typescript
{
  type: string,        // e.g. "error", "console:error", "network:fetch"
  timestamp: number,   // Unix milliseconds (default: now)
  data?: any           // Event-specific payload
}
```

#### Success response (201)

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "occurrenceId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "fingerprint": "abc123def456gh78",
  "deduplicated": false,
  "regression": false,
  "is_regression": false
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | UUID — stable grouped-bug identifier. |
| `occurrenceId` | `string` | UUID — this specific occurrence under the grouped bug. |
| `fingerprint` | `string` | 16-character hex; reports with the same fingerprint are grouped. |
| `deduplicated` | `boolean` | `true` if this report matched an existing open bug. |
| `regression` | `boolean` | `true` if this report matched a previously resolved bug (reopened). |
| `is_regression` | `boolean` | Alias for `regression`. |

#### Error responses

| Status | Body | Cause |
|--------|------|-------|
| 400 | `{ "error": "Validation failed", "details": [...] }` | Invalid payload |
| 400 | `{ "error": "Invalid JSON in request body" }` | Malformed JSON |
| 401 | `{ "error": "Missing or invalid API key" }` | Bad or missing `X-BugTape-Key` |
| 402 | See plan-limit envelope above | Monthly bug limit exceeded |
| 429 | See rate-limit envelope above | Rate limited |
| 500 | `{ "error": "Internal server error", "requestId": "..." }` | Server error |

#### Deduplication

Reports are fingerprinted using:

```
SHA256(errorType + ":" + normalizedMessage + ":" + urlPattern)
```

- **Error type:** extracted from the first error event, or `"manual"` for user-submitted reports.
- **Message normalization:** hex addresses, timestamps, UUIDs, IPs, port numbers, and large numbers are replaced with placeholders.
- **URL normalization:** numeric IDs replaced with `<id>`, UUIDs with `<uuid>`.

If a report's fingerprint matches an existing **open** bug, it increments the report count (`deduplicated: true`). If it matches a **resolved** bug, the bug is reopened (`regression: true`).

#### Signal classification

Each ingest also classifies the payload as `issue`, `watch`, or `diagnostic` (e.g. benign SDK probes) via a heuristic pipeline over event types, auto-report kind, titles, and network status. Diagnostics are hidden from the bug inbox by default; pass `?includeDiagnostics=true` on list/live endpoints to see them.

#### Filtering list endpoints

`GET /v1/bugs` and `GET /v1/bugs/groups` accept, besides `projectId`, `status`, `severity`, `signalClass` and `search`:

- `platform=web|ios|android|react-native|flutter|server|other` — keep bugs with **any** occurrence captured on that platform (the same failure on web and iOS is one bug with `platforms: ["ios","web"]`). Invalid values are `400`.
- `reportedBy=user` — keep bugs with any occurrence someone sent from the in-app bug-report button (`captureSource: "user_report"`). The console's **Reported by users** filter. Also accepted by `GET /v1/bugs` and `GET /v1/bugs/recommended`. Any other value is `400`.
- `assignee=me|<userId>|unassigned` — bugs assigned to the signed-in user, to one user, or to nobody. A named assignee (or `me`) matches only while that user is an active member of the requesting org; `unassigned` means what the row displays: no assignee, or an assignee who is no longer an active member (removed, deactivated, or of another org), whose stored id every read masks. The same rule applies on `GET /v1/bugs` and `GET /v1/bugs/groups`. Groups expose `assignees: string[]`.

Every scalar param `GET /v1/bugs/groups` accepts — `projectId`, `status`, `severity`, `signalClass`, `search`, `platform`, `includeDiagnostics`, `assignee`, `unresolved`, `sort` and `direction` — is parsed through the same one-value-only rule (`parseScalarQueryParam`) before any validation runs: `?status=a&status=b` (or `?status[]=a`) is a clean `400 "status must be provided at most once"`, never silently the first, the last, or an array reaching the query. `GET /v1/bugs` and `GET /v1/bugs/recommended` reject the same way.

`GET /v1/bugs/groups` additionally accepts:

- `sort=last_seen|first_seen|count|severity|title|signal|assignee` and `direction=asc|desc`. The default is `last_seen` `desc` (the pre-existing order, so clients that send neither see no change). `title` sorts the sample title, `signal` puts regressions first then signal classes, `assignee` sorts the group's first display name (name, else email) among assignees who are active members of the requesting org, chosen case-insensitively — the same rule `GET /v1/bugs/recommended` exposes as `assignee_name` — then the name itself, with unassigned groups last in both directions; `first_seen` and `last_seen` break ties straight on `projectId` and `groupKey` ascending; `count`, `severity`, `title`, `signal` and `assignee` first break ties on a fixed `last_seen desc`, then on `projectId` and `groupKey` ascending — so a page is the same on every request (the list paginates with `limit`/`offset`, not a cursor). `assignees` on `/groups`, `/search` and `/recommended` contains only users who are active members of the requesting org: a stale assignment to anyone else (removed, deactivated, or of another org) is dropped from the array, from the sort and, on `/recommended`, from the row's own `assigned_to`. Unknown values are `400`. The console sends both explicitly and defaults to `last_seen` `asc`. The console's Recommended tab is a different list (`GET /v1/bugs/recommended`, the top rows by score) and is ordered client-side over that selected set with the same column contract.

Every paginated bug list ends its ordering on a fixed identity so equal timestamps or scores never reorder between pages: `GET /v1/bugs` (`last_seen desc, project_id, id`), `/groups` (above), `/search` (fused score, then `projectId:groupKey`), `/groups/:groupKey/instances` (`last_seen desc, id`), `/:id/occurrences` (`occurred_at desc, id`) and `/recommended` (`recommended_score desc, last_seen desc, id`). A group's representative (`sampleBugId`, `sampleTitle`, `sampleDescription`, `signatureCanonical`, `signalReason`) is its most recently seen member, ties broken on the greater bug id, in `/groups`, `/search` and the stats queries alike.

`GET /v1/bugs/recommended` returns one row per legacy signature group inside a project (`signature_hash`, or the bug id when unsigned), ranked by that group's best qualifying member (`recommended_score desc, last_seen desc, id`). `total` is the number of groups in `bugs`. The row `id` is that member, and `ack` acts on it. Each row also carries the totals of its legacy signature group inside its own project, computed with the `/groups` rules: `group_key` (`signature_hash`, or the bug id when unsigned; unique only together with `project_id`), `instance_count` (bugs in the group), `report_total` (sum of the members' `report_count`), `occurrence_count` (occurrence rows across every member, or `report_total` when the group has none — the grouped Count; the row's own `report_count` is the representative's value and stays for compatibility), the group's `first_seen` / `last_seen` range, `assignees` (distinct assignee user ids across the members who are active members of the requesting org, raw ids as `/groups` returns them), the bug's own `assigned_to` (null unless that user is an active member), and `assignee_name`, the group's sort key: the case-insensitive minimum display name (name, else email) among those assignees, null when none is. Every aggregate is scoped by the org and the row's project, and names resolve only through the org's `team_memberships` with `users.status = 'active'`, so a foreign, removed or deactivated user id never yields a name. The list is already one row per group. Expand every member through `instances_path` (`/groups/:groupKey/instances?projectId=`). `/recommended` also accepts the inbox's visible filters — `search` (alias `q`), `severity`, `signalClass`, `platform` and `assignee=me|unassigned|<userId>` — applied before the ranking and the limit and matched at the group level: a group is selected when any member matches the search text, platform, signal class or active same-org assignee (`unassigned` means no member has one), and `severity` matches the group's maximum severity; a selected row's group totals are never reduced by a filter. A malformed `assignee`, `severity`, `signalClass` or `platform` is `400`, and so is any repeated (array-valued) `assignee`, `severity`, `signalClass`, `platform`, `search`/`q`, `projectId`, `since` or `limit` (`/bugs` and `/bugs/groups` reject a repeated `assignee` the same way); a well-formed assignee id that is not an active member of the org selects nothing. Because the filters match at the group level, each row also carries the group's displayed evidence, computed with the `/groups` rules over the unfiltered project-and-org-scoped member and occurrence sets: `group_severity` (the maximum member severity — what `severity` compares and what a grouped view shows and sorts by; `severity` / `recommended_severity` stay the representative's own values), `member_id_sample` (at most 8 member bug ids, ascending — not the full set), `member_ids_omitted` (how many ids the sample left out), `instances_path` (where to fetch the rest), `signal_classes`, `signal_families`, `any_regression`, `platforms` (occurrence platforms, first-seen platforms as fallback), `browsers`, `oses`, `session_count` and `user_count`. Every array is ordered ascending, so a group reads byte-for-byte the same whatever order its members were inserted, and no filter ever shrinks these aggregates.

Every group (in `/groups` and `/search`) carries two read-only grouping v3 shadow fields. They describe evidence and never change routing:

- `groupingV3` — `null`, or the latest capture check for the group: `{ version: 3, occurrenceId, observedAt, routable, isolated, reason, confidence }`. `reason` is one of `v3_exact_operation`, `v3_exact_operation_and_native_site`, `v3_native_symbol_site`, `v3_native_image_offset`, `v3_isolated_missing_identity`, `v3_isolated_ambiguous_operation`, `v3_isolated_insufficient_evidence` or `insufficient_legacy_evidence`; `confidence` is `high` or `none`. Key hashes and canonical bytes are never exposed.
- `duplicateCandidateCount` — open proposals whose other canonical issue sits in a **different** displayed group. A pair the group already collapses is not counted.

`/search` hydrates occurrence aggregates (`occurrenceCount`, `sessionCount`, `userCount`, `platforms`) and `signalReason` with the same SQL semantics as `/groups`, keyed by `projectId` + `groupKey`. Identical signatures in two projects stay two groups.

`GET /v1/bugs/groups/:groupKey/instances` accepts `projectId`. A group key is only unique inside a project: when the key exists in more than one of the caller's projects and `projectId` is omitted, the route returns `409` with `code: "GROUP_KEY_AMBIGUOUS"`.

The shadow storage behind these fields is opt-in per project through `projects.grouping_v3_shadow_enabled` (default `false`, SQL-only). It observes and proposes; it never admits, merges, accepts or rejects. Details: `docs/plans/2026-09-09-grouping-v3-shadow-qualification.md`.

### `POST /v1/ingest/presence`

Presence beacon — lightweight upsert of "this session is currently on this page" into the `live_presence` table. Triggers an SSE `presence` event with an org-wide snapshot so the Ops Dashboard can paint active visitors.

**Auth**: `X-BugTape-Key`
**Rate limit**: 100/min per IP (shared with ingest)

**Request body:**

```typescript
{
  sessionId: string,            // required, 1-200 chars
  userId?: string,              // 0-200 chars
  reporterId?: string,          // 0-200 chars
  url?: string,                 // 0-2000 chars
  path?: string,                // 0-1000 chars
  title?: string,               // 0-500 chars
  referrer?: string,            // 0-2000 chars
  eventType?: string,           // 0-100 chars — e.g. "pageview"
  interaction?: object,         // arbitrary interaction payload
  metadata?: object,            // arbitrary metadata
  visibilityState?: string      // 0-50 chars
}
```

**Success (202):**

```json
{ "ok": true }
```

**Error codes:** `400` Validation failed · `401` Missing or invalid API key.

### `POST /v1/ingest/ai-summary`

Server-side AI summary for a bug report. Called by the SDK just before submitting a bug when the caller has **not** configured a client-side `openaiKey`. The server uses its configured multi-provider AI (`openai` / `anthropic` / `google`) to produce a structured summary; nothing is persisted, this is a summarize-only call.

**Auth**: `X-BugTape-Key`
**Rate limit**: 100/min per IP (shared with ingest)

**Request body:**

```typescript
{
  events: Array<object>,         // required, min 1. Server hard-caps at 500 (silent truncation).
  title?: string,                // 0-500 chars
  url?: string,                  // 0-2000 chars
  context?: {
    environment?: string,        // 0-100 chars
    release?: string,            // 0-100 chars
    userAgent?: string,          // 0-500 chars
    userId?: string              // 0-200 chars
  }
}
```

**Success (200):**

```json
{
  "title": "Checkout submit fails with 500 after coupon applied",
  "severity": "high",
  "description": "Console shows TypeError during cart recompute; backend returns 500 on /api/checkout POST immediately after coupon applied.",
  "truncated": false,
  "provider": "openai",
  "model": "gpt-4.1-nano"
}
```

When the caller sends more than 500 events, `truncated` is `true` and the tail is silently discarded before summarisation.

**Error codes:** `400` Validation failed (e.g. missing `events`) · `401` Missing or invalid API key · `429` Rate limit exceeded · `503` AI provider not configured on the server — SDK falls back to submitting the bug without an AI summary.

---

## Bugs (read)

All read endpoints require JWT auth and org scoping: `Authorization: Bearer <token>` + `X-BugTape-Org: <uuid>`.

### `GET /v1/bugs`

List grouped bugs for the organization, with per-bug reporter/occurrence aggregates.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Query parameters:**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `projectId` | `uuid` | — | Filter by project |
| `status` | `string` | — | `new`, `known`, `working`, `resolved`, `silenced` |
| `severity` | `string` | — | `critical`, `high`, `medium`, `low` |
| `signalClass` | `string` | — | `issue`, `watch`, `diagnostic`, or `all` |
| `includeDiagnostics` | `bool` | `false` | Include diagnostic signals when `signalClass` is not set |
| `search` | `string` | — | Full-text `ILIKE` on title and description |
| `limit` | `number` | `50` | Page size (max 200) |
| `offset` | `number` | `0` | Pagination offset |

**Success (200):**

```json
{
  "bugs": [
    {
      "id": "uuid",
      "title": "string",
      "description": "string",
      "severity": "critical|high|medium|low",
      "status": "new|known|working|resolved|silenced",
      "url": "string",
      "fingerprint": "string",
      "report_count": 5,
      "occurrence_count": 5,
      "affected_user_count": 3,
      "affected_session_count": 4,
      "latest_release": "2026.03.08",
      "latest_environment": "production",
      "is_regression": false,
      "signal_class": "issue",
      "signal_family": "runtime_failure",
      "signal_reason": "...",
      "classifier_confidence": "medium",
      "ai_summary": { "...": "..." },
      "project_id": "uuid",
      "project_name": "Default",
      "reporter_count": 2,
      "created_at": "ISO 8601",
      "updated_at": "ISO 8601"
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}
```

### `GET /v1/bugs/stats`

Aggregate counts, a daily timeline, top-10 unresolved bugs, MTTR, the previous period for trend comparison, and a weighted health score.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Query parameters:** `projectId` (optional uuid), `days` (default `30`, 1-365), `deliveryFeed` (`all` | `urgent_critical` | `ui_ux`; humans default `all`, PATs use the stored PAT then project feed).

**Success (200):**

```json
{
  "aggregates": {
    "total": 120, "open": 18, "status_new": 5, "status_known": 4,
    "status_working": 9, "status_resolved": 100, "status_silenced": 2,
    "sev_critical": 2, "sev_high": 6, "sev_medium": 10, "sev_low": 102,
    "total_reports": 318, "avg_resolution_hours": 11.2
  },
  "timeline": [ { "date": "2026-04-01", "bug_count": 3, "report_count": 7 } ],
  "topBugs": [
    { "id": "uuid", "title": "...", "severity": "high", "status": "new",
      "url": "...", "report_count": 41, "first_seen": "...", "last_seen": "..." }
  ],
  "mttr_hours": 11.2,
  "health_score": 47,
  "previous": { "total": 95, "open": 14, "status_new": 6, "status_resolved": 75,
                "sev_critical": 1, "sev_high": 5, "total_reports": 210,
                "avg_resolution_hours": 14.5 },
  "deliveryFeed": "all"
}
```

The health score weights: `critical × 10 + high × 5 + medium × 2 + low × 1 + regressions × 20`. Lower is better.

### `GET /v1/bugs/live`

Most recent bug occurrences across the org — used by the live-monitoring view.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Query parameters:** `limit` (default `50`, max `200`), `includeDiagnostics` (default `false`), `projectId` (optional uuid), `deliveryFeed` (`all` | `urgent_critical` | `ui_ux`).

**Success (200):**

```json
{
  "occurrences": [
    {
      "id": "uuid", "bug_id": "uuid", "project_id": "uuid",
      "reporter_email": "...", "reporter_id": "...",
      "session_id": "...", "end_user_id": "...",
      "release_version": "...", "environment": "production",
      "url": "...", "browser": "Chrome 123", "os": "macOS",
      "event_count": 42, "occurred_at": "ISO 8601",
      "title": "...", "status": "new", "severity": "high",
      "signal_class": "issue", "signal_family": "runtime_failure",
      "signal_reason": "...", "classifier_confidence": "medium",
      "report_count": 5, "project_name": "Default"
    }
  ],
  "limit": 50,
  "deliveryFeed": "all"
}
```

### `GET /v1/bugs/presence`

Active-visitor snapshot for the Ops Dashboard — counts sessions/users active in the last 75 seconds and the top 5 paths.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):**

```json
{
  "active_sessions": 12,
  "active_users": 8,
  "pages": [
    { "path": "/checkout", "active_sessions": 5 },
    { "path": "/",         "active_sessions": 3 }
  ]
}
```

**Error codes:** `400` Organization ID required.

### `GET /v1/bugs/export`

Export bugs as JSON or CSV, with cursor-based pagination via `last_seen`.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Query parameters:**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `format` | `json` / `csv` | `json` | Output format |
| `status` | string | — | Comma-separated (`new,known`) |
| `severity` | string | — | Comma-separated (`critical,high`) |
| `projectId` | uuid | — | Restrict to one project |
| `deliveryFeed` | `all` / `urgent_critical` / `ui_ux` | `all` (humans) | Facet feed; PATs use stored PAT then project |
| `limit` | number | `10000` | Max rows (hard cap `50000`) |
| `after` | ISO 8601 | — | Cursor — only bugs with `last_seen > after` |

**JSON success (200):**

```json
{
  "bugs": [
    { "id": "uuid", "title": "...", "severity": "high", "status": "new",
      "report_count": 5, "url": "...",
      "first_seen": "...", "last_seen": "...", "created_at": "..." }
  ],
  "count": 500,
  "truncated": false,
  "deliveryFeed": "all"
}
```

**CSV success (200):** `Content-Type: text/csv`. Columns: `id, title, severity, status, report_count, url, first_seen, last_seen, created_at`.

Response headers include `X-Query-Ms`, `X-Row-Count`, and `X-Next-After` (next cursor, only when the limit was hit).

### `GET /v1/bugs/:id`

Get a single grouped bug with reporters, recent occurrences, and aggregate counts.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):** a single bug row (same shape as list items) plus `reporters`, `recent_occurrences`, `occurrence_count`, `session_count`, and `affected_user_count`, plus two read-only grouping v3 shadow fields: `groupingV3` (the latest capture check for this canonical issue, same shape as on groups, or `null`) and `duplicateCandidates` (up to 20 open proposals whose other canonical issue sits in a different displayed group: `{ id, otherIssueId, otherTitle, score, reason, confidence, algorithmVersion, state, createdAt }`). There is no accept/reject endpoint; these are evidence, not actions.

**Error codes:** `404` Bug not found.

### `GET /v1/bugs/:id/occurrences`

List individual occurrences grouped under a bug.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Query parameters:** `limit` (default `50`, max `200`), `offset`.

**Success (200):**

```json
{
  "occurrences": [
    { "id": "uuid", "bug_id": "uuid", "project_id": "uuid",
      "reporter_email": "...", "reporter_id": "...", "ip_hash": "...",
      "session_id": "...", "end_user_id": "...",
      "release_version": "...", "environment": "...",
      "url": "...", "user_agent": "...", "viewport": "...",
      "browser": "...", "os": "...",
      "event_count": 42, "metadata": { "...": "..." },
      "occurred_at": "...", "created_at": "..." }
  ],
  "total": 100,
  "limit": 50,
  "offset": 0
}
```

**Error codes:** `404` Bug not found.

### `GET /v1/bugs/:id/events`

Fetch bug events, optionally filtered by type and/or occurrence.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Query parameters:** `type` (event type), `occurrenceId` (uuid), `limit` (default `100`, max `1000`).

**Success (200):**

```json
{
  "events": [
    { "id": "uuid", "bug_id": "uuid", "occurrence_id": "uuid",
      "event_type": "error", "timestamp": "...",
      "data": { "...": "..." } }
  ]
}
```

With `occurrenceId`, the response also has `capture` (what was accepted and what remains). When the browser SDK sealed client details for that capture, `capture.clientTokens` holds the sealed vault `{ v: 1, alg: "ECDH-ES+A256GCM", kid, epk, iv, ct }`; otherwise it is `null`. BugTape cannot open it. The console opens it in the browser with the customer's private key; see [client-detail tokens](./sdk-reference.md#client-detail-tokens).

**Error codes:** `404` Bug not found.

### `GET /v1/bugs/:id/history`

Status-change audit trail, newest first.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):**

```json
{
  "history": [
    { "id": "uuid", "old_status": "new", "new_status": "working",
      "note": "optional note", "changed_at": "...",
      "changed_by_name": "Jack", "changed_by_email": "jack@bugtape.dev" }
  ]
}
```

**Error codes:** `404` Bug not found.

### `GET /v1/bugs/:id/comments`

List comments for a bug, oldest first.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):**

```json
{
  "comments": [
    { "id": "uuid", "bug_id": "uuid", "user_id": "uuid",
      "user_name": "Jack", "user_email": "jack@bugtape.dev",
      "content": "Looking into this...", "created_at": "..." }
  ]
}
```

**Error codes:** `404` Bug not found.

### `GET /v1/bugs/:id/watching`

Returns whether the current user watches this bug.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):**

```json
{ "watching": true }
```

**Error codes:** `404` Bug not found.

### `GET /v1/bugs/:id/similar`

Find related bugs by fingerprint-prefix match and title-word overlap, scored out of 100 and returned top-5.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):**

```json
{
  "similar": [
    { "id": "uuid", "title": "...", "severity": "high", "status": "new",
      "url": "...", "report_count": 5, "first_seen": "...",
      "last_seen": "...", "fingerprint": "abc123...",
      "similarity_score": 80 }
  ]
}
```

**Error codes:** `404` Bug not found.

### `GET /v1/bugs/:id/anomalies`

Heuristic anomaly detection over the bug's events (error cascades, failed-request storms, timeout cascades, rage clicks, auth-refresh loops, request loops, console-error floods, compound failures).

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):**

```json
{
  "anomalies": [
    { "type": "error_cascade", "severity": "high",
      "description": "...", "evidence": ["...", "..."],
      "timeRange": "12:00:01.234 - 12:00:03.100" }
  ],
  "eventCount": 132
}
```

**Error codes:** `404` Bug not found.

### `GET /v1/bugs/stream`

Server-Sent Events stream for real-time bug events. A current expiring human access token is required. The stream checks account revision, membership (or support session) and current project ownership before each delivery. Heartbeats every 15s refresh access and the project list. JWT expiry closes the stream immediately; idle account/workspace revocation closes within 15s plus at most 5s for authorization. Lookup outages, slow readers and a backlog above 100 pending events close the stream; reconnect and fetch current state. Startup lookup outages return 503; rejected sessions return 401. Already-admitted concurrent work is not retroactively cancelled.

**Auth**: `Bearer JWT + X-BugTape-Org`

Event types emitted: `new_bug`, `duplicate`, `regression`, `status_change`, `deleted`, `comment`, `presence`. Payloads include fields such as `title`, `severity`, `url`, `occurrenceId`, `sessionId`, `userId`, `release`, `environment`, `browser`, `os`, and signal-classification fields.

### `GET /v1/bugs/reporters/:email/bugs`

All bugs reported by a specific email address.

**Auth**: `Bearer JWT + X-BugTape-Org`

`:email` is URL-encoded.

> Corrected 2026-08-01. This was previously documented as
> `GET /v1/reporters/:email/bugs`, with a note claiming the parent mount exposed
> it there. It does not: that path returns **404**, and the working path is
> `/v1/bugs/reporters/:email/bugs` (verified against the running stack). Anyone
> integrating from the old entry hit a dead end.

**Success (200):**

```json
{
  "email": "user@example.com",
  "bugs": [
    { "id": "uuid", "title": "...", "severity": "high", "status": "new",
      "url": "...", "first_seen": "...", "last_seen": "...",
      "report_count": 5, "reported_at": "..." }
  ],
  "stats": {
    "total_bugs": 3,
    "first_report": "ISO 8601",
    "last_report": "ISO 8601",
    "severities": { "critical": 1, "high": 1, "medium": 1 }
  }
}
```

---

## Bugs (write)

### `POST /v1/bugs/manual`

Create a bug manually from the console (tester / admin flows). The request is subject to the same fingerprint-based deduplication as SDK ingest.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Request body:**

```json
{
  "projectId": "uuid",
  "title": "string, 3-500 chars",
  "description": "optional, up to 10,000 chars",
  "severity": "critical | high | medium | low",
  "url": "optional, up to 2,000 chars",
  "environment": "optional, up to 100 chars"
}
```

**Success (201):**

```json
{ "id": "uuid", "occurrenceId": "uuid", "deduplicated": false }
```

**Error codes:** `400` Validation failed · `402` Plan limit reached · `404` Project not found.

### `PATCH /v1/bugs/:id`

Update a single bug's status, severity, assignment, and/or append a note to status history.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Request body:**

```json
{
  "status": "new | known | working | resolved | silenced",
  "severity": "critical | high | medium | low",
  "assignedTo": "user-uuid or null",
  "note": "optional note recorded in status history"
}
```

Resolving a bug sets `resolved_at`. Reopening a resolved bug flips `is_regression = true` and emits a `regression` webhook + SSE event. Watchers who are active members of the bug's org receive `status_changed` notifications (a watcher row left by a removed or deactivated member is inert, as it is for comment notifications); assignees are auto-added to watchers and receive an `assigned` notification. `assigned_to` on `GET /v1/bugs` rows and `GET /v1/bugs/:id` is returned only while it names an active member of the requesting org; a stale stored id reads as `null` and the response shape is unchanged. `assignedTo` is `null`/`''` to unassign, otherwise the UUID of an active user who is a member of the requesting org (a pending invitee is rejected until they activate). It is checked before anything is read or written, so a rejected assignment changes no row, adds no watcher, and sends no notification or webhook — even when `status` or `severity` was sent alongside. The response is the same `400 ASSIGNEE_INVALID` for a malformed id, a non-member, a user of another org, and an id that does not exist.

**Success (200):**

```json
{ "success": true }
```

**Error codes:** `400` Invalid status / severity · `400` `ASSIGNEE_INVALID` `assignedTo must be the id of an active member of this organisation` · `404` Bug not found.

### `PATCH /v1/bugs/bulk`

Batch update up to 100 bugs in one call.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Request body:**

```json
{
  "ids": ["uuid", "uuid", "..."],
  "groupRefs": [{ "projectId": "uuid", "groupKey": "signature-or-bug-id" }],
  "groupKeys": ["legacy signature key", "..."],
  "status": "new | known | working | resolved | silenced",
  "severity": "critical | high | medium | low",
  "assignedTo": "user-uuid or null"
}
```

At least one of `ids`, `groupRefs`, `groupKeys` (max 100 each) and at least one of `status`, `severity`, `assignedTo` must be provided. `groupRefs` is the canonical group selector: each `{ projectId, groupKey }` pair expands to every unmerged bug in that project whose `COALESCE(signature_hash, id::text)` matches, after the project is verified to belong to the caller's organisation. `groupKeys` is the legacy selector and is accepted only while each key identifies exactly one project in the organisation. `updated` counts every affected bug.

**Success (200):**

```json
{ "success": true, "updated": 42 }
```

**Error codes:** `400` `ids or groupKeys or groupRefs (array) is required` / `Cannot update more than 100 bugs at once` / `At least one field (status, severity, assignedTo) is required` / Invalid status or severity / malformed `groupRefs` / `ASSIGNEE_INVALID` (same rule and same response as `PATCH /v1/bugs/:id`, checked before the ownership reads) · `404` One or more bugs not found / One or more group reference projects not found · `409` `GROUP_KEY_AMBIGUOUS` when a legacy `groupKey` exists in several projects (retry with `groupRefs`); nothing is updated.

### `POST /v1/bugs/:id/comments`

Add a comment to a bug. Auto-subscribes the commenter. Mentions (`@user@example.com`) notify mentioned teammates who are active members of the bug's org and auto-subscribe them; a pending, deactivated or foreign-org address gets no notification and no watcher row.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Request body:**

```json
{ "content": "string, up to 10,000 chars" }
```

**Success (201):**

```json
{
  "id": "uuid", "bug_id": "uuid", "user_id": "uuid",
  "user_name": "Jack", "user_email": "jack@bugtape.dev",
  "content": "...", "created_at": "ISO 8601"
}
```

**Error codes:** `400` Comment content is required / too long · `404` Bug not found.

### `POST /v1/bugs/:id/watch`

Subscribe the current user to this bug's notifications.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):** `{ "watching": true }`

**Error codes:** `404` Bug not found.

### `DELETE /v1/bugs/:id/watch`

Unsubscribe the current user.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):** `{ "watching": false }`

**Error codes:** `404` Bug not found.

### `POST /v1/bugs/merge`

Merge up to 20 source bugs into a target bug. Reporters, occurrences, events, comments, attachments, watchers, and status history are re-parented to the target; source bugs are deleted. Counts and timestamps are aggregated.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Request body:**

```json
{
  "sourceIds": ["uuid", "uuid", "..."],
  "targetId": "uuid"
}
```

**Success (200):**

```json
{ "success": true, "targetId": "uuid", "mergedCount": 3 }
```

**Error codes:** `400` Missing ids / target-in-sources / too many bugs · `404` One or more bugs not found · `500` Merge failed.

### `DELETE /v1/bugs/:id`

Permanently delete a bug and all cascading data (reporters, occurrences, events, attachments, watchers, status history, comments). Emits a `deleted` SSE event.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):**

```json
{ "success": true, "deleted": "uuid" }
```

**Error codes:** `404` Bug not found.

### `POST /v1/bugs/:id/analyze`

Deep AI analysis of a bug and up to 500 of its events. Returns a root cause, a causal chain, severity assessment, suggested fix, and a named pattern classification. Tracked against the org's AI usage.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):**

```json
{
  "analysis": {
    "rootCause": { "summary": "...", "category": "authentication", "technicalDetail": "..." },
    "causalChain": [
      { "step": 1, "event": "...", "timestamp": "ISO 8601",
        "role": "root_cause", "explanation": "..." }
    ],
    "severity": { "level": "high", "reasoning": "...", "userImpact": "..." },
    "suggestedFix": { "summary": "...", "steps": ["...", "..."] },
    "pattern": { "name": "AUTH_TOKEN_REFRESH_LOOP", "confidence": "high" },
    "confidence": "medium"
  },
  "stats": {
    "total_events": 180, "errors": 5, "network": 80,
    "console": 40, "user_actions": 10,
    "anomalies": ["3 failed HTTP requests"],
    "duration_seconds": 18.4
  }
}
```

**Error codes:** `404` Bug not found · `500` Analysis failed · `503` AI service not configured.

### `POST /v1/bugs/:id/events/:eventId/ai`

AI assessment of a single event. Two modes: `explain` (default) or `fix`.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Query parameters:** `mode=explain|fix`.

**Success (200):**

```json
{ "assessment": "plain-text assessment", "mode": "explain" }
```

**Error codes:** `404` Event not found · `500` AI assessment failed · `503` AI service not configured.

---

## Projects and API keys

### `GET /v1/projects`

List projects for the caller's org, with bug counts.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):**

```json
{
  "projects": [
    { "id": "uuid", "org_id": "uuid", "name": "Default", "slug": "default",
      "platform": "...", "created_at": "...",
      "bug_count": 12, "new_bug_count": 3 }
  ]
}
```

### `POST /v1/projects`

Create a project. Requires role `admin`, `manager`, or `member`.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Request body:**

```json
{ "name": "Project Name", "orgId": "uuid" }
```

`orgId` must match the caller's org.

**Success (201):**

```json
{ "id": "uuid", "name": "Project Name", "slug": "project-name" }
```

**Error codes:** `400` name and orgId required · `402` Plan limit reached · `403` Organization mismatch.

### `POST /v1/projects/:id/keys`

Generate a new API key for a project. Requires role `admin`, `manager`, or `member`.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Request body:**

```json
{ "env": "live", "label": "iPhone production", "expiresAt": null }
```

`env` is `"live"` (default) or `"test"`; other values are rejected. It selects the
key prefix, not a separate environment or data store. Use a separate project for
isolation. Optional `label` is trimmed, 1–80 characters. Optional `expiresAt` is
an ISO timestamp in the future, at most 365 days away. Omitted/null expiry keeps
the key active until revoked, preserving existing clients. Existing keys are not
changed. Creation and revocation recheck role and active account state under the
same organization lock as team changes. The key can capture within its project;
it cannot act as a human JWT or agent PAT.

**Success (201):**

```json
{
  "key": "bt_live_abcdefghijklmnopqrstuvwxyz123456",
  "note": "Save this key — it will not be shown again."
}
```

**Error codes:** `400` Invalid label/environment/expiry · `403` Current role/account cannot manage keys · `404` Project not found.

### `GET /v1/projects/:id/keys`

List a project's API keys. Only prefix and metadata are returned (the raw key is never stored in plaintext).

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):**

```json
{
  "keys": [
    { "id": "uuid", "key_prefix": "bt_live_abc", "label": "default",
      "is_active": true, "last_used": "...", "created_at": "...", "expires_at": null }
  ]
}
```

### `DELETE /v1/projects/:id/keys/:keyId`

Soft-delete (revoke) an API key by setting `is_active = false`. Requires role `admin`, `manager`, or `member`.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):**

```json
{ "success": true, "revoked": "bt_live_abc" }
```

**Error codes:** `404` API key not found or already revoked.

---

## Team

### `GET /v1/team`

List the current org's team members with their notification preferences.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):**

```json
{
  "members": [
    { "id": "uuid", "email": "...", "name": "...", "avatar_url": null,
      "role": "admin", "joined_at": "...",
      "email_level": "full", "slack_enabled": false,
      "in_app_enabled": true, "digest_freq": "realtime" }
  ]
}
```

### `POST /v1/team/invite`

Invite a team member by email. Creates a `pending_invite` user when needed. A new teammate receives a one-use48-hour setup link; an active teammate receives a workspace sign-in link. Requires role `admin` or `manager`.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Request body:**

```json
{
  "email": "teammate@example.com",
  "role": "admin | manager | member | tester | viewer",
  "orgId": "uuid"
}
```

`orgId` must match the caller's org. Role defaults to `"member"`. Optional `resend:true` requires an existing membership and preserves its current role. Resending invalidates the previous setup link.

**Success (201):**

```json
{ "success": true, "userId": "uuid", "invitation": { "state": "pending", "emailStatus": "queued", "expiresAt": "ISO8601" } }
```

**Error codes:** `400` Validation failed · `402` Plan limit reached · `403` Organization mismatch.

`state` is `pending` or `active`; active accounts have null `expiresAt`. `emailStatus:queued` means the queue accepted the mail, not that the recipient received it. `unavailable` means no configured provider or no queue acceptance; the membership remains and an administrator can retry. Setup secrets are never returned to the administrator.

### `PATCH /v1/team/:userId`

Change a team member's role. Requires role `admin` or `manager`. You cannot downgrade yourself to `viewer`.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Request body:**

```json
{ "role": "admin | manager | member | tester | viewer" }
```

**Success (200):**

```json
{
  "success": true,
  "membership": { "org_id": "uuid", "user_id": "uuid", "role": "member" }
}
```

**Error codes:** `400` Invalid role / Cannot downgrade yourself to viewer · `404` Member not found.

### `DELETE /v1/team/:userId`

Remove a team member from the org (and their notification prefs). In the same transaction their assignments on this org's bugs are cleared and their watcher rows on this org's bugs removed, so nothing keeps routing work or notifications to them here; bugs, comments, history and their memberships and data in other orgs are untouched. Requires role `admin` or `manager`. You cannot remove yourself.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):**

```json
{ "success": true }
```

**Error codes:** `400` Cannot remove yourself from the team · `404` Member not found.

### `GET /v1/team/activity`

Recent activity feed across the org (comments, status changes, new bugs), newest first.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Query parameters:** `limit` (default `30`, max `100`).

**Success (200):**

```json
{
  "activity": [
    { "type": "comment", "actor": "Jack",
      "summary": "comment text…", "bug_title": "...", "bug_id": "uuid",
      "ts": "ISO 8601" },
    { "type": "status_change", "actor": "Jack",
      "summary": "new → working", "bug_title": "...", "bug_id": "uuid",
      "ts": "ISO 8601" },
    { "type": "new_bug", "actor": "system",
      "summary": "...", "bug_title": "...", "bug_id": "uuid",
      "ts": "ISO 8601" }
  ]
}
```

### `PATCH /v1/team/:userId/notifications`

Update a team member's notification preferences.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Request body (all optional):**

```json
{
  "emailLevel": "full | notification | digest | off",
  "slackEnabled": true,
  "slackWebhook": "https://hooks.slack.com/...",
  "inAppEnabled": true,
  "digestFreq": "realtime | hourly | daily"
}
```

**Success (200):**

```json
{ "success": true }
```

---

## Notifications

All notification endpoints require org scoping.

### `GET /v1/notifications`

List in-app notifications for the current user in the current org, plus the unread count.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Query parameters:** `unread=true` (only unread), `limit` (default `50`, max `200`).

**Success (200):**

```json
{
  "notifications": [
    { "id": "uuid", "user_id": "uuid", "org_id": "uuid",
      "type": "assigned | comment | mention | status_changed | critical | high | regression | handoff_failed | handoff_stalled | agent_picked_up | agent_pr | system_down | system_recovered | push_test",
      "title": "...", "body": "...", "bug_id": "uuid", "actor_id": "uuid",
      "read": false, "created_at": "..." }
  ],
  "unreadCount": 4
}
```

### `POST /v1/notifications/:id/read`

Mark a single notification as read.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):** `{ "success": true }`

**Error codes:** `404` Notification not found.

### `POST /v1/notifications/read-all`

Mark all of the user's notifications in this org as read.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):** `{ "success": true }`

### Web Push and the iOS app (2026-10-01; APNs 2026-10-02)

One pipeline writes each event to the person's bell and, when they chose that event, pushes it to every browser they turned notifications on in and to every BugTape iOS app install they signed in to (APNs; on an issue the notification offers Take it and Send to agent). APNs payloads cross Apple's servers in clear text, so an email address in the title or body reads "someone" on the iPhone; the bell and Web Push keep the full text. Every `/v1/auth` answer is `Cache-Control: no-store`. A push carries only the title, a short body and a console link (`/console/issues/<id>?org=<workspace>`); it is encrypted for the browser (RFC 8291) and signed with the server's VAPID key. Pushes respect personal quiet hours and the project's alert policy, skip rows already read in the console, and drop a browser the push service reports as gone. All push routes need a human session (`Bearer JWT + X-BugTape-Org`); agent PATs get `403`.

| Method | Path | Description |
|--------|------|-------------|
| GET | `/v1/notifications/push/config` | `{ enabled, publicKey, apns }` — `publicKey` is the VAPID application server key for `pushManager.subscribe`; `apns` says the server can push to the BugTape iOS app |
| GET | `/v1/notifications/push/subscriptions` | `{ count, devices }` — this person's subscribed browsers and iOS app installs |
| POST | `/v1/notifications/push/subscriptions` | Body: a `PushSubscription` JSON `{ endpoint, keys: { p256dh, auth } }`. `201`. The endpoint must be a known push service (Google, Mozilla, Apple, Microsoft) over https: `400 PUSH_ENDPOINT_INVALID`; bad keys `400 PUSH_SUBSCRIPTION_INVALID`; push not set up on the server `501 PUSH_NOT_CONFIGURED`. An endpoint already registered moves to the person signed in now only with the same browser keys (`409 PUSH_SUBSCRIPTION_CONFLICT` otherwise). At most 20 browsers per person; the oldest is dropped. |
| DELETE | `/v1/notifications/push/subscriptions` | Body `{ endpoint }` — removes this person's subscription only |
| POST | `/v1/notifications/push/devices` | The BugTape iOS app registers an install: `{ token, environment: "sandbox"\|"production", installationId, bundleId, appVersion? }` (`token` = the APNs device token in hex; `installationId` = a UUID the app keeps in its Keychain). `201`. `400 PUSH_DEVICE_INVALID`; `400 PUSH_DEVICE_WRONG_APP` when `bundleId` is not the app this server pushes to; `501 PUSH_NOT_CONFIGURED` without APNs. A token held by another person moves only when the same `installationId` sends it (`409 PUSH_DEVICE_CONFLICT`); an install's older token is dropped. At most 10 installs per person. |
| DELETE | `/v1/notifications/push/devices` | Body `{ token }` — sign-out removes this install (this person's only) |
| GET | `/v1/notifications/push/preferences` | `{ events }` for this workspace |
| PUT | `/v1/notifications/push/preferences` | Body `{ events: { <kind>: boolean } }`, merged over the saved choice. Kinds: `critical`, `regression`, `high`, `handoff_failed`, `handoff_stalled`, `agent_picked_up`, `agent_pr`, `assigned`, `mentioned`, `comment`, `status_changed`, `system`. Defaults: on for critical, regression, handoff_failed, handoff_stalled, agent_pr, assigned, mentioned, system; off for high, agent_picked_up, comment, status_changed. |
| POST | `/v1/notifications/push/test` | Pushes "Notifications are on" to this person's browsers and iOS app installs, whatever the switches. Adds `browsers` and `devices` (`{ sent, failed }` each); `outcome` is `refused` when a push service said no for a reason other than a gone subscription (for example an APNs key or topic problem). `409 NO_PUSH_SUBSCRIPTION`, `429` within 20 seconds of the last test. Returns `{ ok, outcome }`. |

Events: assigned, mentioned, comment and status change come from the existing in-app notifications; a new Critical (or High, opt-in) issue and a regression reach every active member of the project's workspace when the project's alert policy lets the alert through; a manual Send to agent tells its sender when every destination failed for good (`handoff_failed`) or when nobody collected or picked it up within 30 minutes (`handoff_stalled`, checked every 5 minutes, once per send); `agent_picked_up` and `agent_pr` reach the issue's watchers, assignee and the person who sent it, never the person who acted; `system_down` and `system_recovered` (switch `system`) reach superadmins only, when a part of the system is down on 2 checks in a row and when it recovers. They open `/console/admin?tab=system` and sit in the superadmin's oldest workspace. Each superadmin also gets an email, whatever the switch says, except during their email quiet hours.

---

## Integrations

Integrations drive Slack, Discord, GitHub Issues, and generic webhook deliveries. All routes require org scoping.

### `GET /v1/integrations`

List integrations for a project. Sensitive config values (tokens, secrets, full webhook URLs) are redacted.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Query parameters:** `projectId` (uuid, required).

**Success (200):**

```json
{
  "integrations": [
    { "id": "uuid", "type": "slack | discord | webhook | github",
      "name": "...", "config": { "url": "https://hooks.slack.com/***", "token": "***" },
      "events": ["new_bug", "regression", "status_change"],
      "is_active": true, "created_at": "...", "updated_at": "..." }
  ]
}
```

**Error codes:** `400` projectId is required · `404` Project not found.

### `POST /v1/integrations`

Create an integration.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Request body:**

```json
{
  "projectId": "uuid",
  "type": "slack | discord | webhook | github",
  "name": "Optional label",
  "config": {
    "url": "https://hooks.slack.com/services/...",
    "secret": "optional HMAC secret for generic webhook",
    "token": "GitHub token (github only)",
    "repo": "owner/repo (github only)"
  },
  "events": ["new_bug", "regression", "status_change"],
  "deliveryFeed": "all | urgent_critical | ui_ux",
  "minSeverity": "critical | high | medium | low",
  "bearerToken": "optional, webhook and agent only"
}
```

`deliveryFeed`, `minSeverity`, and `bearerToken` apply to `webhook` and `agent`. Leave `config.secret` blank and BugTape generates one. The secret and bearer are encrypted and write-only. `config.preset: "claude_routine"` requires `https://api.anthropic.com/v1/claude_code/routines/<id>/fire` and sends `{"text":"…"}` plus `anthropic-beta` and `anthropic-version`. Payload, headers, and the verifier: [webhooks.md](./webhooks.md).

SSRF guard: webhook URLs that resolve as loopback, link-local, private, multicast, or IPv4-mapped IPv6 addresses are rejected. In production, non-HTTPS URLs are also rejected.

**Success (201):**

```json
{
  "id": "uuid",
  "type": "slack",
  "name": "...",
  "events": ["new_bug", "regression", "status_change"],
  "is_active": true,
  "created_at": "...",
  "signingSecret": "whsec_… shown once for webhook and agent"
}
```

**Error codes:** `400` Validation failed / Invalid webhook URL / Private URL / Bad GitHub repo format · `402` Plan limit reached · `404` Project not found.

### `PATCH /v1/integrations/:id`

Update any of `name`, `config`, `events`, `is_active`.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Request body:**

```json
{
  "name": "string",
  "config": { "...": "..." },
  "events": ["new_bug"],
  "is_active": true
}
```

**Success (200):** the updated integration row.

**Error codes:** `400` No fields to update · `404` Integration not found.

### `DELETE /v1/integrations/:id`

Delete an integration.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):** `{ "success": true }`

**Error codes:** `404` Integration not found.

### `POST /v1/integrations/:id/test`

Send a test payload through the integration.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):** `{ "success": true }`

**Error codes:** `404` Integration not found · `502` Webhook delivery failed.

### `POST /v1/integrations/:id/rotate-secret`

Issue a new signing secret for a `webhook` or `agent` destination. The previous secret keeps verifying for 24 hours (`X-BugTape-Signature-256` carries two `v1` values).

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):** `{ "id", "signingSecret", "signing", "bearer" }`. `signingSecret` is shown once.

**Error codes:** `404` Integration not found · `400` this destination type has no signing secret.

### `GET /v1/integrations/:id/deliveries`

List retained deliveries and delivery results, ordered by creation time ascending.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Query parameters:** `limit` (default `20`, max `100`), `offset`, optional `status` (`pending`, `deferred`, `success`, `failed`, `canceled`). Filters apply across all history; `total` counts matching records.

**Success (200):**

```json
{
  "deliveries": [
    { "id": "uuid", "event_type": "new_bug",
      "status": "success", "attempts": 1,
      "response_code": 200, "error_message": null,
      "created_at": "...", "completed_at": "...",
      "deferred_until": null, "can_retry": false }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}
```

**Error codes:** `404` Integration not found.

### `POST /v1/integrations/:id/deliveries/:deliveryId/retry`

Retry a single failed delivery only when `can_retry` is true. Current connection settings, subscriptions and policy are checked again. Capture delivery retries share the queue receipt lock and a five-attempt outbound budget. Quiet-hour checks and failed database preparation do not spend that budget.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):** `{ "success": true }`

**Error codes:** `404` Retryable delivery not found / Integration not found · `409` Delivery held or excluded by current rules · `502` Retry failed.

### Generic webhook payload

For integrations of type `webhook` and `agent`, BugTape POSTs JSON for every event the project's alert policy allows. Events: `new_bug`, `regression`, `status_change`, `comment`, `assigned`, `recommended_bug`, `agent_notify`, `agent_update`, `test`. `agent_notify` adds `trigger` (`auto` | `manual`); `agent_update` adds `agentAction` (`working` | `pr_opened`), `agentActor` and optional `prUrl`. Neither is held by the alert policy's severity floor or quiet hours; the integration's `events` list decides. New integrations default to `new_bug`, `regression`, `status_change`, plus `agent_notify` (agent, webhook) and `agent_update` (slack, discord, telegram, whatsapp, imessage, webhook). Migration 066 added the same to existing integrations.

```json
{
  "event": "new_bug",
  "source": "bugtape",
  "title": "Bug Title",
  "severity": "high",
  "url": "https://example.com/page",
  "bugId": "uuid",
  "projectId": "uuid",
  "occurrenceId": "uuid",
  "fingerprint": "a1b2c3d4e5f60718",
  "platform": "ios",
  "release": "1.4.0",
  "environment": "production",
  "userId": "u_123",
  "sessionId": "s_…",
  "status": "new",
  "oldStatus": "resolved",
  "reportCount": 5,
  "description": "...",
  "consoleUrl": "https://app.bugtape.ai/console/issues/<id>",
  "userEmail": "user@example.com",
  "evidence": {
    "mcp": "get_repro_context({ bugId: \"…\", occurrenceId: \"…\" })",
    "events": "https://app.bugtape.ai/v1/bugs/<id>/events?occurrenceId=<occ>",
    "occurrences": "https://app.bugtape.ai/v1/bugs/<id>/occurrences",
    "users": "https://app.bugtape.ai/v1/bugs/<id>/users"
  },
  "version": "2026-10-08",
  "timestamp": "2026-02-28T12:00:00Z"
}
```

`version` is `2026-10-08`. Ingest events (`new_bug`, `regression`) carry the occurrence facts (`occurrenceId`, `platform`, `release`, `environment`, `userId`, `sessionId`, `evidence`); status/comment/assign events carry what they know. Fields are additive — never removed. The canonical example, feed filters, and the 15-minute triage wait are in [webhooks.md](./webhooks.md).

Headers on every webhook and agent delivery:

```
Content-Type: application/json
X-BugTape-Event: <event>
X-BugTape-Event-Id: <id>                      (when a domain event id exists)
X-BugTape-Delivery-Id: <id>                   (when a delivery row exists)
X-BugTape-Signature: sha256=<hmac-hex>        (current secret, HMAC-SHA256 of the raw body)
X-BugTape-Signature-256: t=<unix>,v1=<hex>    (HMAC-SHA256 of "<t>.<raw body>"; second v1 during 24h rotation)
Authorization: Bearer <token>                 (only when a bearer is stored)
User-Agent: BugTape-Webhook/1.0               (BugTape-AgentWebhook/1.0 for the agent type)
```

Verify `X-BugTape-Signature-256` and reject `|now - t| > 300` seconds. The older `X-BugTape-Signature` stays for existing receivers.

Delivery: Slack, Discord, and the other chat destinations use one attempt plus 4 retries, then the dead-letter log. Webhook and agent deliveries on the capture path wait 10 seconds, 1 minute, 5 minutes, 30 minutes, and 2 hours, then `webhook-dlq`. Alerts → Delivery log shows retained work and results; eligible failed records offer manual retry. Capture webhooks held by quiet hours retain the same delivery ID and wait for a minute policy sweep, including after restart. `deferred_until` is the next check time, not a promised send time. Permanent exclusions cancel retained work. Manual/legacy status-change alerts are not retained when quiet hours suppress initial routing. Delivery remains at-least-once: a remote acceptance followed by a worker failure can produce a duplicate. Respond `2xx` within 10 s. See [webhooks.md](./webhooks.md) and [agents.md](./agents.md).

---

## Org usage

### `GET /v1/org/usage`

Return the caller's org plan, limits, and current usage (bugs this month, projects, team members, integrations, etc.). Used by the console Billing page.

**Auth**: `Bearer JWT + X-BugTape-Org`

**Success (200):** the org's usage object (shape produced by `getOrgUsage`; includes at least `plan`, per-resource `limit` / `current`, and overage flags).

**Error codes:** `404` Organization not found.

**Workspace (2026-10-08).** The response includes `workspace: { id, name }` — the workspace the session or agent token belongs to. A person can belong to several workspaces and one agent token belongs to one, so the `bugtape` CLI prints this name on `connect`, `init`, `login` and `whoami`. Agent tokens with any scope can read it.

`features.mcp` is `true` on every plan (2026-10-01). `features.mcp_source` says how agent reads are paid: `plan` (Pro/Team/Enterprise, unmetered) or `credits` (Free and Prepaid credits, 2 credits a read). `none` is kept in the type for older readers and is no longer returned.

---

## Billing — Prepaid credits, saved card, budgets (2026-09-24, migration 065)

**Stripe Managed Payments (2026-10-01, the default).** Stripe, through Link, is the seller of record: it adds and files sales tax, VAT and GST for the buyer's country and handles fraud, disputes and payment support. Every Checkout session (`pack: "credits"` and `plan: "pro"`, hosted or embedded) sets `managed_payments.enabled = true`, the BugTape branding (name, the `b` badge from `/assets/brand/icon-512.png`, paper background, rust accent) and never sends parameters Managed Payments refuses (`automatic_tax`, `tax_id_collection`, `payment_method_types`, `customer_update`, `invoice_creation`, `custom_text`). Embedded sessions use `redirect_on_completion: "if_required"`, so a card payment finishes inside the console dialog. Managed Payments only sells through Checkout, so while it is on: `POST /v1/billing/card-setup-session` returns `410 CARD_SETUP_RETIRED`; auto top-up never runs; `GET /v1/billing/budget` returns `autoTopUpAvailable: false` and `autoTopUp: false`; `PUT /v1/billing/budget` with `autoTopUp: true` returns `400 AUTO_TOP_UP_UNAVAILABLE`. The monthly budget stays a hard cap on credit packs people buy (`0` = no cap). Set `STRIPE_MANAGED_PAYMENTS=false` for a Stripe account without Managed Payments; everything below then applies as written.

**Tiers.** Free · Prepaid credits · Pro ($29/mo, 10,000 credits a month, about $2.90 per 1,000) · Team · Enterprise. Prepaid credits are one-off packs with no monthly subscription: $10 buys 2,000 credits (about $5 per 1,000; Stripe price `STRIPE_PRICE_ID_CREDITS`). **Prepaid credits never expire** — the monthly reset touches only the included grant (`credit_included`), never `credit_prepaid`.

**Credits put a workspace on Pro (2026-09-26).** Free is the only limited plan. A workspace whose billing plan is Free but holds a prepaid balance (`credit_prepaid > 0`) gets every Pro limit and feature: 5,000 new issues a month, unlimited projects, 10 members, 10 integrations, 30-day retention, MCP and 200 AI requests a day. `GET /v1/org/usage` returns the effective `plan` (`pro`), `plan_source` (`subscription` | `credits` | `free`) and `billing_plan` (`free`). Plan-limit 402s, the retention purge and the one-free-workspace rule use the same rule. When the balance reaches 0 the workspace is back on Free limits until it buys more. The Pro subscription keeps its 10,000 included credits a month and free agent reads; credit workspaces pay agent reads and AI from their credits.

**Auto top-up (2026-09-26, migration 070).** With auto top-up on, a prepaid balance below `autoTopUpBelowCredits` (default 200) charges the saved card for one pack ($10 → 2,000 credits) off-session through a Stripe PaymentIntent (`metadata.kind = credits_auto_top_up`). Every charge runs under the per-org billing lock and `assertWithinBudget(..., { automatic: true })`, so it never passes the monthly budget. The Stripe idempotency key is per org, month and sequence, so a retry never charges twice. A decline switches auto top-up off. `payment_intent.succeeded` / `payment_intent.payment_failed` settle charges that finish later. Triggers: spending prepaid credits, turning the switch on, and a 15-minute sweep. `GET /v1/billing/budget` adds `autoTopUpBelowCredits`, `pack` and `lastAutoTopUp { status, message, at }`; `PUT` accepts `autoTopUpBelowCredits` (0–100,000).

**MCP on Free and Prepaid credits (2026-10-01).** `POST /v1/org/agent-pats` accepts every plan; `402 MCP_PLAN_REQUIRED` is no longer returned. For orgs without an MCP plan, each agent-PAT read of `GET /v1/bugs/:id/events` with `limit > 1` costs **2 credits**, taken like other work: included credits first (Free includes 150 a month), then prepaid (`credit_ledger.reason = 'mcp_repro_read'`). This is the read behind `get_repro_context`, `get_bug_events` and the `bugtape://bugs/{id}/repro` resource. Reads with `limit <= 1` and every other agent read are free. Pro/Team/Enterprise and human sessions are never charged. Included plus prepaid below 2 → `402 { code: "credits_exhausted" }`.

**Budget rules.** A budget is USD cents per UTC calendar month. `0` (the default) means BugTape never charges the saved card automatically. A budget above 0 is a hard cap on every charge path: a credit-pack checkout that would take month-to-date spend over the budget is refused with `402 BUDGET_EXCEEDED` before Stripe is called. Month-to-date spend = sum of `credit_ledger.amount_cents` for paid credit packs (`reason = 'credits_pack'`, `delta > 0`) this month. An admin-started pack checkout with budget 0 is allowed (the admin pays in Stripe). Auto top-up is off by default and is stored only when a card is on file and the budget is above 0; see Auto top-up above for how it charges.

All three endpoints need a direct workspace-admin session: `denyAgentPat` + `requireOrgAccess('admin')` + no support impersonation (same guards as checkout and portal). They return `403` otherwise.

### `GET /v1/billing/usage`

How credits ticked down this month. Any member of the org (human session).

Returns `plan`, `monthlyGrant` (null = unlimited), `includedLeft` (resets on the 1st, UTC), `prepaidLeft` (never expires), `periodStart`, `spentThisMonth`, `byKind` (one row per kind of work: `reason`, `label`, `credits` each, `count`, `spent`), `daily` (credits spent per day over the last 30 days, days with spend only) and `priceList`.

### `GET /v1/billing/invoices`

The org's Stripe invoices and credit-pack receipts, newest first, at most 24. Direct workspace admins only (same guards as the other billing routes). Each item: `id`, `number`, `createdAt`, `status`, `totalCents`, `currency`, `description`, `hostedUrl`, `pdfUrl` (Stripe-hosted). Empty list when the org has no Stripe customer; 501 without Stripe keys.

`POST /v1/billing/portal` now also opens for Prepaid credits orgs that saved a card but have no subscription.

Budgets count still-open credit-pack Checkouts from the last 24 hours (migration 067), under a per-org lock, so two checkouts opened together cannot pass the cap. Stripe `payment_method.attached` / `payment_method.detached` keep `paymentMethodOnFile` true to Stripe; removing the card also turns `autoTopUp` off.

### `GET /v1/billing/budget`

Database-only — works without Stripe keys.

**Success (200):**

```json
{
  "monthlyBudgetCents": 3000,
  "autoTopUp": false,
  "paymentMethodOnFile": true,
  "monthToDateSpendCents": 1000,
  "month": "2026-09-01"
}
```

### `PUT /v1/billing/budget`

**Body:** `{ "monthlyBudgetCents"?: integer 0..10000000 | null, "autoTopUp"?: boolean }` — at least one field. `null` or `0` means never charge and forces `autoTopUp` to `false`.

**Success (200):** the same shape as `GET`.

**Error codes:** `400 VALIDATION_ERROR` (bad type, range, unknown field, empty body) · `400 AUTO_TOP_UP_REQUIRES_BUDGET` · `400 AUTO_TOP_UP_REQUIRES_CARD` · `400 AUTO_TOP_UP_UNAVAILABLE` (Managed Payments on) · `403`.

### `POST /v1/billing/card-setup-session`

Stripe Checkout in `mode: "setup"`: saves a card and charges nothing. Reuses the org's Stripe customer (subscription or earlier saved card); otherwise Checkout creates one (`customer_creation: "always"`). Offers `card` and `link`, so a card saved with Stripe Link (for another organization or elsewhere) can be picked after a one-time code. Cards stay per organization; auto top-up can charge a Link payment method.

**Body:** `{ "returnTo"?: "setup" | "settings" }` (default `settings`). Returns to `/console/setup?billing=card_saved|card_cancel` or `/console/billing?billing=card_saved|card_cancel`.

**Success (200):** `{ "url": "https://checkout.stripe.com/…" }`

**Error codes:** `400` bad `returnTo` · `403` · `410 CARD_SETUP_RETIRED` (Managed Payments on, the default) · `501` Billing not configured (`STRIPE_SECRET_KEY` unset).

**Webhook.** `checkout.session.completed` with `mode: "setup"` (or `metadata.kind: "card_setup"`) stores `billing_budgets.stripe_customer_id` and sets `payment_method_on_file = true`. It never creates a subscription or changes `organizations.plan`. A paid credit pack now records `amount_cents` (from `amount_total`) on its ledger row; an unpaid pack session grants nothing.

### `POST /v1/billing/create-checkout-session` — budget check

`{ "pack": "credits" }` now runs the budget check first: `402 { code: "BUDGET_EXCEEDED", monthlyBudgetCents, monthToDateSpendCents, chargeCents: 1000 }` when the pack would go over a budget above 0.

---

## Admin (superadmin only)

Every endpoint below requires `Authorization: Bearer <token>` for a user whose email is listed in the `ADMIN_EMAILS` env var. Non-superadmin callers receive `403 Forbidden`.

### Invite codes (migration 071)

A friends-and-family link that starts a new workspace with prepaid credits. The console has an **Admin → Invite codes** tab for these.

- `GET /v1/admin/signup-codes` → `{ codes: AdminSignupCode[] }`, newest first. Each has `code`, `link` (`/console/register?code=…`), `credits`, `maxUses` (null = no cap), `uses`, `note`, `expiresAt`, `disabledAt`, `status` (`active` | `disabled` | `expired` | `used_up`) and `createdByEmail`.
- `POST /v1/admin/signup-codes` with body `{ credits?=10000, maxUses?, expiresAt?, note?, code?, prefix? }` → `201 { code }`. Without `code`, one is generated as `PREFIX-XXXXXX` (default `FRIENDS`, no look-alike characters). A chosen code that exists → `409 SIGNUP_CODE_EXISTS`.
- `POST /v1/admin/signup-codes/:id/disable` → `{ code }`. The link stops working; workspaces that already used it keep their credits.

Each workspace redeems a code once. `max_uses` is enforced under a row lock, so concurrent signups cannot pass the cap. Credits land in `credit_ledger` with reason `signup_code`.

### `GET /v1/admin/overview`

System-wide counts plus 30 days of growth.

**Success (200):**

```json
{
  "counts": {
    "users": 120, "organizations": 37, "projects": 52,
    "bugs": 1842, "events": 410230, "api_keys": 85, "waitlist_pending": 12
  },
  "growth": [
    { "date": "2026-03-18", "users": 118, "organizations": 36, "bugs": 1801 }
  ]
}
```

### System status (migration 083)

The console's **Admin → System** page. A pg-boss job (`system-status-check`, every 5 minutes) probes every part of the system and stores one row per component in `system_checks`; rows older than 8 days are deleted by the same job (the page shows 24 h and 7 d), in batches of 2,000 for at most ~2 s per run. One probe run at a time per API process: a GET, a forced check and the scheduled job share it. Probes are bounded (one pool client each, a 3 s `statement_timeout`, at most 4 at once, a 4 s deadline per probe) and only call npm, PyPI and DNS for `app.bugtape.ai` / `bugtape.ai` (cached 10 minutes). Output holds names, counts, versions, booleans and timestamps only — never key values, connection strings, private hosts or email addresses. Contract: `AdminSystemStatusResponse` in `packages/contracts/src/admin.ts`.

- `GET /v1/admin/system-status` → `AdminSystemStatusResponse`. Answers from the newest stored run when it is younger than 10 minutes (`source: "stored"`); otherwise it probes now, stores that run and answers `source: "live"`. Each component has `status` (`ok` | `warn` | `down` | `off` | `unknown`), a one-sentence `summary`, `problems`, `lastUpdatedAt` + `lastUpdatedLabel` (what the date means, e.g. `"published 0.1.1 on npm"`, `"migration 083 applied"`, `"deployed or restarted (process start)"`), `lastActivityAt`, `latencyMs`, `metrics`, 24 hourly `history` buckets (worst status in each hour, oldest first, `null` = no check) and `uptimePct24h` (checks with `ok`, `warn` or `off` ÷ all checks in 24 h except `unknown`; `null` when none are counted). `monitor.retentionDays` is 8. `overall` is the worst of `ok` / `warn` / `down` (off and unknown do not count). `edges` describe the diagram.
- `POST /v1/admin/system-status/check` → the same shape with `source: "live"`, from a forced run that skips the 10-minute cache of registry and DNS answers. One forced run per 15 seconds per API process; inside that window the last result is returned. A forced run already in progress is shared; a live or scheduled run in progress is waited for, then a fresh run starts.
- `GET /v1/admin/system-status/:componentId/history?hours=24|168` → `{ componentId, hours, checks: [{ checkedAt, status, latencyMs, summary }] }`, newest first, at most 2,016 rows. `hours` defaults to 24; any other value → `400`. An unknown component id → `404`.

Component ids: `sdk-browser`, `sdk-node`, `sdk-python`, `sdk-swift`, `extension`, `console`, `ios-app`, `mcp`, `cli`, `dns`, `api`, `ingest`, `realtime`, `jobs`, `static`, `rate-limit`, `postgres`, `openai`, the triage classifier provider, `stripe`, `email`, `apns`, `web-push`, `slack`, `discord`, `github`, `webhook`, `growth`, `evidence-storage`, `symbol-worker`, `grouping-v3`, `redis`, `native-fatal`, `github-ci`, `testflight`.

### `GET /v1/admin/organizations`

List all organizations with member/project/bug counts.

**Query parameters:** `search`, `limit` (default `50`, max `200`), `offset`.

**Success (200):** `{ "organizations": [...], "total": N, "limit": 50, "offset": 0 }`

### `GET /v1/admin/customers`

Customer view grouped by org — enriched with primary contact, last activity, and counts.

**Query parameters:** `search`, `stage` (`trial|active|paused|churned|internal`), `plan` (`free|pro|team|enterprise`), `billingStatus` (`unassigned|manual|paid|past_due`), `limit`, `offset`.

**Success (200):**

```json
{
  "customers": [
    { "id": "uuid", "name": "...", "slug": "...", "plan": "free", "credit_prepaid": 10000,
      "lifecycle_stage": "trial", "billing_status": "manual",
      "admin_notes": "...", "created_at": "...", "updated_at": "...",
      "primary_contact_name": "...", "primary_contact_email": "...",
      "primary_contact_role": "admin", "primary_contact_verified": true,
      "use_case": "...", "waitlist_status": "completed",
      "waitlist_created_at": "...", "waitlist_completed_at": "...",
      "member_count": 3, "project_count": 2, "active_keys": 4,
      "bug_count": 42, "open_bug_count": 5, "last_bug_seen": "...",
      "last_activity_at": "..." }
  ],
  "total": 37, "limit": 50, "offset": 0
}
```

`plan` is the billing plan. `credit_prepaid` is the balance of bought credits; any amount above 0 puts a Free workspace on Pro limits.

### `POST /v1/admin/customers/:orgId/credits`

Gives a workspace prepaid credits without a payment (**Add credits** in Admin → Customers). Any balance puts a Free workspace on Pro limits.

**Request body:** `{ "credits": 5000, "note": "Launch help" }`. `credits` is 1–1,000,000; `note` is optional, at most 200 characters.

**Success (201):** `{ "orgId": "uuid", "orgName": "...", "credits": 5000, "prepaid": 5000 }`. `prepaid` is the balance after the grant.

The grant is one transaction and one `credit_ledger` row with reason `admin_grant`, `amount_cents` 0, `note` and `granted_by` (migration 072). It never counts as spend against the workspace's monthly budget.

**Error codes:** `400` credits or note invalid · `403` not a superadmin · `404` Customer not found.

### `GET /v1/admin/customers/:orgId`

Full customer profile: organization + team + projects.

**Success (200):**

```json
{
  "customer": { "...": "org row + primary contact + waitlist info" },
  "team": [
    { "id": "uuid", "email": "...", "name": "...",
      "email_verified": true, "last_login": "...",
      "role": "admin", "joined_at": "..." }
  ],
  "projects": [
    { "id": "uuid", "name": "...", "slug": "...", "platform": "...",
      "created_at": "...", "bug_count": 42, "active_keys": 2,
      "last_key_used": "..." }
  ]
}
```

**Error codes:** `404` Customer not found.

### `POST /v1/admin/customers`

Create a customer organization manually. If `contactEmail` matches an existing user, they become the admin and receive an invite email; otherwise a waitlist row is created with a 7-day approval token and the approved-signup email is sent.

**Request body:**

```json
{
  "orgName": "Acme Corp",
  "contactEmail": "owner@acme.com",
  "contactName": "Optional Name",
  "plan": "free | pro | team | enterprise",
  "lifecycleStage": "trial | active | paused | churned | internal",
  "billingStatus": "unassigned | manual | paid | past_due",
  "useCase": "Optional free-text"
}
```

**Success (201):**

```json
{
  "customer": {
    "id": "uuid", "name": "Acme Corp", "slug": "acme-corp",
    "plan": "free", "lifecycle_stage": "trial", "billing_status": "manual"
  },
  "project": { "id": "uuid", "name": "Default", "slug": "default" }
}
```

**Error codes:** `400` orgName and contactEmail are required.

### `POST /v1/admin/customers/:orgId/team`

Add (or promote) a workspace member from owner mode. Sends an invite email.

**Request body:**

```json
{
  "email": "teammate@example.com",
  "name": "Optional Name",
  "role": "admin | manager | member | tester | viewer"
}
```

**Success (201):** `{ "success": true, "userId": "uuid", "role": "member" }`

**Error codes:** `400` Valid email and role are required · `404` Customer not found.

### `PATCH /v1/admin/customers/:orgId`

Update a customer's plan, lifecycle stage, billing status, and/or admin notes.

**Request body (at least one field required):**

```json
{
  "plan": "free | pro | team | enterprise",
  "lifecycleStage": "trial | active | paused | churned | internal",
  "billingStatus": "unassigned | manual | paid | past_due",
  "adminNotes": "string or empty to clear"
}
```

**Success (200):** `{ "customer": { ...org row... } }`

**Error codes:** `400` Invalid plan / lifecycle stage / billing status / No valid fields to update · `404` Customer organization not found.

### `GET /v1/admin/users`

List all users with their org memberships.

**Query parameters:** `search`, `limit` (default `50`, max `200`), `offset`.

**Success (200):** `{ "users": [ ... ], "total": N, "limit": 50, "offset": 0 }`. Each user has an `orgs` array `[{ orgId, role, orgName }]`.

### `POST /v1/admin/support/session`

Start an explicit 8-hour owner support session into a customer workspace. The console uses it for **Admin → Open a client** (a search box at the top of every Admin tab), the Customers tab's Support button, and the support banner's **Switch client**. Starting a session also clears the admin's selected project, so the client's own default project loads.

**Request body:** `{ "orgId": "uuid" }`

**Success (201):**

```json
{
  "session": {
    "id": "uuid", "orgId": "uuid",
    "orgName": "...", "orgSlug": "...",
    "mode": "full", "expiresAt": "ISO 8601"
  }
}
```

**Error codes:** `400` orgId is required · `404` Customer not found.

### `GET /v1/admin/projects`

List all projects with the parent org name and counts.

**Query parameters:** `limit` (default `50`, max `200`), `offset`.

**Success (200):** `{ "projects": [...], "total": N, "limit": 50, "offset": 0 }`. Each row includes `org_name`, `bug_count`, `active_keys`.

### `GET /v1/admin/api-keys`

List all API keys with their project and org names.

**Query parameters:** `limit` (default `50`, max `200`), `offset`.

**Success (200):** `{ "keys": [...], "total": N, "limit": 50, "offset": 0 }`.

### `GET /v1/admin/activity`

Unified recent-actions feed (new bugs, status changes, user signups).

**Success (200):**

```json
{
  "activity": [
    { "type": "bug_filed | status_change | user_signup",
      "id": "uuid", "summary": "...", "detail": "...", "ts": "ISO 8601" }
  ]
}
```

### `GET /v1/admin/db/tables`

Row counts for every user table (read from `pg_stat_user_tables`).

**Success (200):**

```json
{ "tables": [ { "table_name": "bug_reports", "row_count": 1842 } ] }
```

### `GET /v1/admin/db/tables/:table`

Browse rows in an allowlisted table, with sensitive columns replaced by `'[REDACTED]'`.

**Allowlist:** `organizations, users, team_memberships, projects, api_keys, bug_reports, bug_reporters, bug_events, bug_attachments, bug_comments, bug_status_history, notification_preferences, notifications, bug_watchers, refresh_tokens, integrations, password_reset_tokens, ai_usage, integration_deliveries, waitlist_entries`.

**Redacted columns:** `password_hash`, `key_hash`, `token_hash`.

**Query parameters:** `limit` (default `50`, max `200`), `offset`.

**Success (200):**

```json
{
  "table": "users",
  "columns": ["id", "email", "...", "password_hash"],
  "rows": [ { "id": "uuid", "email": "...", "password_hash": "[REDACTED]" } ],
  "total": 120, "limit": 50, "offset": 0
}
```

**Error codes:** `400` `Table '<name>' is not in the allowed list`.

### `GET /v1/admin/api-key-stats`

API-key usage overview.

**Success (200):**

```json
{
  "total_keys": 85,
  "active_keys": 80,
  "used_last_24h": 42,
  "never_used": 5
}
```

### `GET /v1/admin/ai-usage`

AI usage statistics.

**Query parameters:** `days` (default `30`, max `90`).

**Success (200):**

```json
{
  "summary": {
    "total_calls": 1200,
    "total_input_tokens": 450000,
    "total_output_tokens": 98000,
    "total_tokens": 548000
  },
  "daily": [ { "date": "2026-04-01", "calls": 18, "tokens": 6200 } ],
  "byFeature": [
    { "feature": "deep_analysis", "provider": "openai", "model": "gpt-4o",
      "calls": 120, "tokens": 320000 }
  ],
  "days": 30
}
```

---

## CORS

The API accepts requests from origins configured via `CORS_ORIGIN` (if unset it logs a warning and defaults to same-origin). Hosted Fly sets `CORS_ORIGIN=*` so customer sites can POST `/v1/ingest` with `X-BugTape-Key`. That `*` is required for multi-tenant ingest today. Do not silently tighten it. Allowed headers:

```
Content-Type, Authorization, X-BugTape-Key, X-BugTape-Org
```

Allowed methods: `GET, POST, PATCH, DELETE, OPTIONS`.

---

## Route index

Quick reference — every route, auth requirement, and a one-line description.

### Health

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET    | `/v1/health` | none | Process + cheap DB ping (Fly liveness; not a ship signal) |
| GET    | `/v1/health/deep` | none for status; health token or superadmin for checks | Public `{ status, timestamp }`. Detail adds DB, migrations, jobs/DLQ, redis. HTTP 200 can still mean `jobs: degraded` |

### Auth

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST   | `/v1/auth/register` | none | Open self-serve signup; creates user and workspace |
| GET    | `/v1/auth/approval/:token` | none | Validate an approval link token |
| POST   | `/v1/auth/complete-signup` | none | Consume approval token, create account + tokens |
| POST   | `/v1/auth/login` | none | Password login → access + refresh tokens |
| POST   | `/v1/auth/refresh` | none | Swap refresh token for a fresh access token |
| GET    | `/v1/auth/me` | Bearer JWT | Current user profile + org memberships |
| GET    | `/v1/auth/whats-new` | Bearer JWT + Org | Activity since the user's last login |
| POST   | `/v1/auth/send-verification` | Bearer JWT | Send verification email to current user |
| POST   | `/v1/auth/resend-verification` | none | Public resend (enumeration-safe) |
| POST   | `/v1/auth/verify-email` | none | Consume an email-verification token |
| POST   | `/v1/auth/forgot-password` | none | Request a password-reset link |
| POST   | `/v1/auth/reset-password` | none | Consume reset token + set new password |

### Ingestion

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST   | `/v1/ingest` | X-BugTape-Key | Submit a bug report |
| POST   | `/v1/ingest/presence` | X-BugTape-Key | Live-presence beacon |
| POST   | `/v1/ingest/ai-summary` | X-BugTape-Key | Server-side AI summary for a pending report |

### Bugs (read)

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET    | `/v1/bugs` | Bearer JWT + Org | List grouped bugs |
| GET    | `/v1/bugs/stats` | Bearer JWT + Org | Aggregates, MTTR, health score |
| GET    | `/v1/bugs/live` | Bearer JWT + Org | Recent occurrences across the org |
| GET    | `/v1/bugs/presence` | Bearer JWT + Org | Active visitor snapshot |
| GET    | `/v1/bugs/export` | Bearer JWT + Org | Export bugs (JSON or CSV) |
| GET    | `/v1/bugs/:id` | Bearer JWT + Org | Single bug with reporters + recent occurrences |
| GET    | `/v1/bugs/:id/occurrences` | Bearer JWT + Org | Occurrences under a bug |
| GET    | `/v1/bugs/:id/events` | Bearer JWT + Org | Events for a bug or occurrence |
| GET    | `/v1/bugs/:id/history` | Bearer JWT + Org | Status-change audit trail |
| GET    | `/v1/bugs/:id/comments` | Bearer JWT + Org | List comments |
| GET    | `/v1/bugs/:id/watching` | Bearer JWT + Org | Is current user watching? |
| GET    | `/v1/bugs/:id/similar` | Bearer JWT + Org | Similar-bugs scoring |
| GET    | `/v1/bugs/:id/anomalies` | Bearer JWT + Org | Heuristic anomaly detection |
| GET    | `/v1/bugs/stream` | Bearer JWT + Org | SSE real-time stream |
| GET    | `/v1/reporters/:email/bugs` | Bearer JWT + Org | All bugs by reporter email |

### Bugs (write)

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST   | `/v1/bugs/manual` | Bearer JWT + Org | Create a bug from the console |
| PATCH  | `/v1/bugs/:id` | Bearer JWT + Org | Update status / severity / assignment |
| PATCH  | `/v1/bugs/bulk` | Bearer JWT + Org | Bulk update up to 100 bugs |
| POST   | `/v1/bugs/:id/comments` | Bearer JWT + Org | Add comment (auto-subscribe, @mentions) |
| POST   | `/v1/bugs/:id/watch` | Bearer JWT + Org | Watch a bug |
| DELETE | `/v1/bugs/:id/watch` | Bearer JWT + Org | Unwatch a bug |
| POST   | `/v1/bugs/merge` | Bearer JWT + Org | Merge sources into a target |
| DELETE | `/v1/bugs/:id` | Bearer JWT + Org | Permanently delete a bug + cascades |
| POST   | `/v1/bugs/:id/analyze` | Bearer JWT + Org | Deep AI analysis of a bug |
| POST   | `/v1/bugs/:id/events/:eventId/ai` | Bearer JWT + Org | AI explain/fix for an event |

### Projects & API keys

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET    | `/v1/projects` | Bearer JWT + Org | List projects |
| POST   | `/v1/projects` | Bearer JWT + Org | Create a project |
| POST   | `/v1/projects/:id/keys` | Bearer JWT + Org | Generate an API key |
| GET    | `/v1/projects/:id/keys` | Bearer JWT + Org | List API keys (masked) |
| DELETE | `/v1/projects/:id/keys/:keyId` | Bearer JWT + Org | Revoke an API key (soft-delete) |

### Team

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET    | `/v1/team` | Bearer JWT + Org | List team members |
| POST   | `/v1/team/invite` | Bearer JWT + Org | Invite by email |
| PATCH  | `/v1/team/:userId` | Bearer JWT + Org | Change role |
| DELETE | `/v1/team/:userId` | Bearer JWT + Org | Remove from org |
| GET    | `/v1/team/activity` | Bearer JWT + Org | Recent team activity feed |
| PATCH  | `/v1/team/:userId/notifications` | Bearer JWT + Org | Update notification prefs |

### Org usage

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET    | `/v1/org/usage` | Bearer JWT + Org | Plan, limits, and current usage |

### Notifications

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET    | `/v1/notifications` | Bearer JWT + Org | List notifications + unread count |
| POST   | `/v1/notifications/:id/read` | Bearer JWT + Org | Mark one as read |
| POST   | `/v1/notifications/read-all` | Bearer JWT + Org | Mark all as read |
| GET    | `/v1/notifications/push/config` | Bearer JWT + Org (human) | Push enabled + VAPID public key |
| GET/POST/DELETE | `/v1/notifications/push/subscriptions` | Bearer JWT + Org (human) | This person's subscribed browsers |
| POST/DELETE | `/v1/notifications/push/devices` | Bearer JWT + Org (human) | This person's iOS app installs (APNs) |
| GET/PUT | `/v1/notifications/push/preferences` | Bearer JWT + Org (human) | Which events push, per workspace |
| POST   | `/v1/notifications/push/test` | Bearer JWT + Org (human) | Send "Notifications are on" |

### Integrations

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET    | `/v1/integrations` | Bearer JWT + Org | List integrations for a project |
| POST   | `/v1/integrations` | Bearer JWT + Org | Create integration |
| PATCH  | `/v1/integrations/:id` | Bearer JWT + Org | Update integration |
| DELETE | `/v1/integrations/:id` | Bearer JWT + Org | Delete integration |
| POST   | `/v1/integrations/:id/test` | Bearer JWT + Org | Send a test payload |
| GET    | `/v1/integrations/:id/deliveries` | Bearer JWT + Org | Delivery history |
| POST   | `/v1/integrations/:id/deliveries/:deliveryId/retry` | Bearer JWT + Org | Retry a failed delivery |

### Admin (superadmin only)

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET    | `/v1/admin/overview` | Superadmin | Global counts + 30-day growth |
| GET    | `/v1/admin/system-status` | Superadmin | Every system component: status, last update, metrics, 24 h history |
| POST   | `/v1/admin/system-status/check` | Superadmin | Force a live probe run (one per 15 s per process) |
| GET    | `/v1/admin/system-status/:componentId/history` | Superadmin | Stored checks for one component (`hours=24` or `168`) |
| GET    | `/v1/admin/organizations` | Superadmin | All orgs with counts |
| GET    | `/v1/admin/customers` | Superadmin | Customer-view orgs with filters |
| GET    | `/v1/admin/customers/:orgId` | Superadmin | Customer profile + team + projects |
| POST   | `/v1/admin/customers` | Superadmin | Manually create a customer |
| POST   | `/v1/admin/customers/:orgId/team` | Superadmin | Add/promote a workspace member |
| PATCH  | `/v1/admin/customers/:orgId` | Superadmin | Update plan / stage / billing / notes |
| GET    | `/v1/admin/users` | Superadmin | List users + memberships |
| POST   | `/v1/admin/support/session` | Superadmin | Start 8-hour support session |
| GET    | `/v1/admin/projects` | Superadmin | All projects with org + counts |
| GET    | `/v1/admin/api-keys` | Superadmin | All API keys with project + org |
| GET    | `/v1/admin/activity` | Superadmin | Unified recent actions |
| GET    | `/v1/admin/db/tables` | Superadmin | Row counts for all tables |
| GET    | `/v1/admin/db/tables/:table` | Superadmin | Browse rows in an allowlisted table |
| GET    | `/v1/admin/api-key-stats` | Superadmin | API-key usage overview |
| GET    | `/v1/admin/ai-usage` | Superadmin | AI usage summary + breakdown |

---

## Agent notified

BugTape notifies the project's agent and hands over evidence. It does not fix code. The agent opens the PR; a human reviews it.

### POST /v1/bugs/:id/notify-agent

"Send to agent". **JWT** (agent PATs refused), role admin, manager or member. Fires every agent channel for the bug's project and records one `agent_notifications` row per channel:

- `agent` / `webhook` integrations subscribed to `agent_notify` — event `agent_notify`.
- `github` — reuses the bug's existing GitHub issue delivery, else opens one through the normal issue path.
- `mcp` — an active subscribe-scoped agent PAT that can read the project; stays `queued` until an MCP `listen` session collects it.

A repeat call within 60 s returns the earlier batch with `200` and `reused: true`. `201` otherwise.

```json
{ "bugId": "…", "reused": false, "noChannel": false,
  "notifications": [ { "id": "…", "trigger": "manual", "channel": "agent", "channelName": "Claude runner",
                       "status": "delivered", "detail": null, "createdAt": "…", "deliveredAt": "…" } ] }
```

With no channel: one row `{ "channel": null, "status": "no_channel", "detail": "Connect an agent first" }` and `noChannel: true`. Status is `queued | delivered | failed | no_channel`; a linked webhook delivery's live outcome wins over the stored row. **Errors:** `401`, `403` (PAT or viewer/tester), `404` bug not in the org.

### GET /v1/bugs/:id/agent-status

**JWT**, any member. The timeline Notified → Picked up → PR opened.

```json
{ "bugId": "…", "state": "pr_opened",
  "notified": { "at": "…", "trigger": "auto", "channels": [ … ] },
  "pickedUp": { "at": "…", "by": "pat:bt_pat_ab12", "note": "on it" },
  "prOpened": { "at": "…", "url": "https://github.com/o/r/pull/7" },
  "canConnect": false, "history": [ … ] }
```

`state` is `none | no_channel | notified | working | pr_opened`. Picked up comes from `agent_ack = 'working'` and `agent_ack_by`.

### POST /v1/bugs/:id/ack — `prUrl`

Optional `prUrl` (absolute `https://`, no credentials, at most 2048 characters) with `action: "working"`; `400 PR_URL_INVALID` otherwise. Stored as `bug_reports.agent_pr_url`. The first `working` ack and each new `prUrl` send `agent_update` to the project's human destinations.

### GET / PUT /v1/projects/:id/agent-settings

GET: **JWT**, any member. PUT: **JWT**, admin or manager; support sessions refused. Body `{ "autoNotify"?: boolean, "minSeverity"?: "critical" | "high" | "medium" | "low" }` (at least one). Response `{ "settings": { "projectId", "autoNotify", "minSeverity" } }`. Default off, `high`. When on, the capture outbox sends `agent_notify` for each new issue or regression at or above `minSeverity`; a failure is recorded as a `failed` row and never fails capture.

### GET /v1/projects/:id/agent-notifications?after=

MCP listen feed. Agent PAT with `subscribe` (project grants honored) or **JWT**. Without `after`: MCP-channel handoffs still `queued` from the last 24 h. With `after` (the previous `cursor`): rows created after it. Returned queued rows become `delivered`. Response `{ "cursor": "…", "notifications": [ { "id", "bugId", "trigger", "createdAt", "title", "severity" } ] }`.

### GET / PUT /v1/projects/:id/datadog

GET: **JWT**, any member. PUT: **JWT**, admin or manager; agent tokens and support sessions refused. Body `{ "site": "datadoghq.com" | "us3.datadoghq.com" | "us5.datadoghq.com" | "datadoghq.eu" | "ap1.datadoghq.com" | "ap2.datadoghq.com" | "ddog-gov.com" | null }`. Response `{ "settings": { "projectId", "site" } }`. Default `null` (no links). `GET /v1/bugs/:id` returns the site as `datadog_site`, and each `recent_occurrences` row carries `datadog` (`trace_id`, `span_id`, `service`, `env`, `rum_session_id`) when the report's `metadata.datadog` had them. See [Use BugTape with Datadog](./datadog.md).

### GET / PUT /v1/projects/:id/attention

GET: **JWT** or an agent token with `setup_capture`, `get_repro_context`, `suggest_fix` or `subscribe`. PUT: **JWT** (admin, manager or member) or an agent token with `setup_capture`. Support sessions can read and cannot write. Body is any subset of `{ "interests", "lookingFor", "concerns", "specialCase" }`. Each value is text of at most 500 characters. An empty string clears that note. Omitted keys stay. Response `{ "attention": { interests, lookingFor, concerns, specialCase } }`. Stored on `projects.settings.attention`. No model call.

## Endpoints added since this document was last revised

Reconciled 2026-08-01 by diffing every `router.<verb>` registration in
`packages/api/src/routes/` against the headings above. The document had drifted
badly: 84 endpoints documented against 106 in source, with whole feature areas —
Alerts, Tickets, Billing, Portfolio — absent entirely, and one entry pointing at
a path that 404s (see the correction under `GET /v1/bugs/reporters/:email/bugs`).

Auth column: **JWT** = `Bearer JWT + X-BugTape-Org`; **JWT-only** = bearer token,
no org header; **Superadmin** = JWT plus an `ADMIN_EMAILS` address; **Key** =
`X-BugTape-Key`; **Agent** = `X-Agent-Token` + `X-BugTape-Org` (local-only —
`AGENT_TOKEN` is deliberately unset in production).

### Alerts / escalations

| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | `/v1/alerts/policy` | JWT | Per-project alert policy: severity floor, excludes, quiet hours |
| PUT | `/v1/alerts/policy` | JWT | Upsert that policy |
| GET | `/v1/alerts/overview` | JWT | Escalation overview for the project |
| GET | `/v1/alerts/digests?projectId=<uuid>&after=<batch-id>` | JWT | Caller-only email batch history for the selected project |
| POST | `/v1/alerts/digests/:batchId/resolution` | Recipient JWT | Record receipt or explicitly request another copy of an uncertain batch |

Digest history returns `batches`, `pendingEvents` and `nextCursor`. Omit `after`
for the first page. Pages contain at most 50 batches, ordered by creation time then
ID ascending. Pass the returned cursor unchanged; foreign cursors return 404.
Counts include only the selected project. No recipient address or token is returned.
States are queued, sending, succeeded, retryable, permanent_failure, cancelled and
outcome_unknown. Succeeded means provider acceptance, not inbox delivery. Unknown
outcomes do not automatically resend. Instant email is not in this batch history.

Each batch includes `generation`, `resolution`, `allowedActions` (`received`,
`retry`, `reason`) and `batchProjectCount`. A resolution is an immutable recipient
decision, separate from the original provider outcome. `received` is shown as
“Confirmed by you”; it does not change the provider state to succeeded.

Resolution accepts a closed body: `projectId`, UUID `requestId`, integer
`expectedGeneration` (0–3), and `action` (`received` or `retry`). Retry requires
`acceptDuplicateRisk: true`; received must omit it. Only the current recipient
can act. Support sessions, PATs and capture keys cannot mutate these decisions.
An identical nonce/body returns the same receipt with `replayed: true`.
Changed nonce content or stale state returns 409. On an unknown response or
`DIGEST_BUSY`, retain and retry the exact request. Cancellation cannot undo a commit.

Retry authorizes the whole email batch, including events from other projects.
It queues the same batch/intent IDs with a new generation, preserving cumulative
attempts. Current email preferences, access, issue exclusions and quiet hours
still apply. A queue receipt does not mean sent. Limits are three manual retries
and eight cumulative send/preparation attempts. A recipient can still confirm
receipt at the retry limit. Responses include only a safe decision receipt:
`id`, `batchId`, `projectId`, `requestId`, `action`, `generation`, `nextGeneration`
and `createdAt`. History and resolution responses use `Cache-Control: no-store`.

### Tickets (Kanban)

| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | `/v1/tickets` | JWT or Agent | List tickets for the org |
| GET | `/v1/tickets/:id` | JWT or Agent | Single ticket |
| POST | `/v1/tickets` | JWT or Agent | Create |
| PATCH | `/v1/tickets/:id` | JWT or Agent | Update fields |
| POST | `/v1/tickets/:id/move` | JWT or Agent | Move between columns |
| DELETE | `/v1/tickets/:id` | JWT or Agent | Delete |

### Billing

| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | `/v1/billing/create-checkout-session` | JWT | Start a Stripe checkout |
| POST | `/v1/billing/portal` | JWT | Stripe customer-portal session |
| GET | `/v1/billing/subscription` | JWT | Current subscription state |
| GET | `/v1/billing/budget` | JWT (direct admin) | Budget, card on file, month-to-date spend |
| PUT | `/v1/billing/budget` | JWT (direct admin) | Set monthly budget / auto top-up flag |
| POST | `/v1/billing/card-setup-session` | JWT (direct admin) | Setup-mode Checkout: save a card, no charge (410 with Managed Payments; 501 without Stripe) |

### Portfolio

| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | `/v1/portfolio/overview` | JWT-only | Cross-org rollup over every org the caller belongs to. Deliberately **not** org-scoped — isolation comes from the caller's own `team_memberships`, so no org header is read. |

### Bugs — grouping and search

| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | `/v1/bugs/groups` | JWT | Signature-grouped issue list (the console inbox) |
| GET | `/v1/bugs/groups/:groupKey/instances` | JWT | Instances within one group (`projectId` required when the key spans projects, else `409 GROUP_KEY_AMBIGUOUS`) |
| GET | `/v1/bugs/search` | JWT | Trigram + vector search, fused by RRF. Honors `deliveryFeed`. |
| GET | `/v1/bugs/reporters/:email/bugs` | JWT | Bugs reported by one email |

### Auth — account lifecycle and GDPR

| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | `/v1/auth/switch-org` | JWT-only | Re-issue tokens against another org the user belongs to |
| POST | `/v1/auth/data-export` | JWT-only | Request a GDPR data export |
| POST | `/v1/auth/data-delete/request` | JWT-only | Request account deletion |
| POST | `/v1/auth/data-delete/confirm` | Token | Confirm deletion via emailed token |

### Admin — maintenance

| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | `/v1/admin/backfill-signatures` | Superadmin | Recompute `signature_hash` across existing bugs |
| POST | `/v1/admin/gdpr/delete-org` | Superadmin | Hard-delete an org and all its data |

### Health

| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | `/v1/health/deep` | None for status; `X-BugTape-Health-Token` or superadmin session for checks | Public status is `ok` or `degraded`. Detail adds DB latency, migration drift, email/AI configuration, pg-boss job depths. Names, booleans and counts only — no secrets. `503` when the DB or migrations are unhealthy. HTTP 200 does not mean `jobs.status === 'ok'`. |

### Ingest aliases on the bugs router

`POST /v1/bugs`, `/v1/bugs/presence` and `/v1/bugs/ai-summary` are the same
handlers as the `/v1/ingest` equivalents, reachable on the console mount and
guarded by `X-BugTape-Key`. Clients should use the `/v1/ingest` paths; these
exist because both live on one router.

> **Not an alias any more:** `/v1/ingest` used to mount the *entire* bugs router,
> so every console route also answered under `/v1/ingest/*`. That was closed on
> 2026-08-01 — the ingest mount now carries only `POST /v1/ingest`,
> `/v1/ingest/presence` and `/v1/ingest/ai-summary`.

## End-user attribution

Every occurrence carries a canonical **`userKey`**: the app's own user id (SDK `identify()` → ingest `userId`), else the reporter email, else an anonymous key derived from the hashed client IP. It is the same expression behind every "users affected" count, so rosters always add up.

### GET /v1/bugs/:id/users

**Auth**: `Bearer JWT + X-BugTape-Org` (agent PATs with `get_repro_context`, `suggest_fix` or `subscribe`)

Who hit this bug — one row per end user, newest last-seen first. Query: `limit` (default 50, max 200), `offset`.

```json
{
  "users": [
    {
      "userKey": "u_123", "kind": "user", "endUserId": "u_123", "email": "sara@acme.com",
      "firstSeen": "2026-09-01T10:00:00.000Z", "lastSeen": "2026-09-02T10:00:00.000Z",
      "occurrenceCount": 3, "platforms": ["ios", "web"], "lastRelease": "1.4.0",
      "lastEnvironment": "production", "lastOccurrenceId": "…"
    }
  ],
  "total": 1, "limit": 50, "offset": 0
}
```

`kind` is `user` | `email` | `anonymous`. `GET /v1/bugs/:id/occurrences?userKey=<key>` narrows the occurrence list (and its `total`) to that user.

### GET /v1/end-users?q=&limit=

Prefix search over user ids and emails inside the org (`q` ≥ 2 chars). Returns `{ query, users: [{ userKey, kind, endUserId, email, lastSeen, occurrenceCount, bugCount }] }`.

### GET /v1/end-users/:userKey/timeline?projectId=&limit=&offset=

Everything one end user hit across every bug and project in the org, newest first. `404` when the key has no occurrences in this org.

```json
{
  "identity": { "userKey": "u_123", "kind": "user", "endUserId": "u_123", "emails": ["sara@acme.com"],
                "firstSeen": "…", "lastSeen": "…", "occurrenceCount": 5, "bugCount": 3, "sessionCount": 2, "platforms": ["ios"] },
  "occurrences": [
    { "id": "…", "bug_id": "…", "project_id": "…", "project_name": "Shop", "title": "TypeError: …",
      "severity": "high", "status": "new", "signal_class": "issue", "platform": "ios",
      "release_version": "1.4.0", "environment": "production", "url": "app://checkout",
      "session_id": "…", "browser": null, "os": "iOS", "occurred_at": "…" }
  ],
  "total": 5, "limit": 100, "offset": 0
}
```

MCP: `get_bug_users(bugId)` and `get_user_timeline(userKey)` expose the same data to agents.

### POST /v1/projects/:id/test-event

**Auth**: `Bearer JWT + X-BugTape-Org` (human sessions only)

Setup wizard proof. Body `{ "platform": "web" | "ios" | "android" | "react-native" | "flutter" | "server" }` (default `web`). Mints one real occurrence through the normal ingest pipeline — grouping, credits, webhooks, SSE, agent queue — titled `SetupCheckError: BugTape test event received from <Platform>`, with the calling user as the affected end user. Returns the ingest `201` envelope plus `platform`.

### GET /v1/projects/:id/onboarding-test

**Auth**: `Bearer JWT + X-BugTape-Org` (human sessions)

The first-bug walkthrough's server receipt. Before the sample exists it returns `{ "test": null, "agentStatus": null }`. After, `test` holds the pinned `bugId`, `occurrenceId` and `projectId`, `isSample: true`, `purpose: "pipe_check"`, `sdkInstallationVerified: false`, evidence counts, `agentRead` (`{ at, by }` or null) and `agentAcknowledged` (`{ at, by, note }` or null); `agentStatus` reports the send and delivery separately. `Cache-Control: no-store`.

### POST /v1/projects/:id/onboarding-test

**Auth**: `Bearer JWT + X-BugTape-Org` (human sessions; member, manager or admin)

Creates the project's one labelled sample report (`OnboardingTestError: Your first BugTape pipe check`) with three synthetic events. Empty body only. `201` creates it, `200` returns the existing one; concurrent calls make one report. It uses no credits or issue quota and starts no alerts, triage or automatic agent work. A connection counts only when an agent PAT reads that exact occurrence (a non-empty events read) and then acknowledges it with `not_actionable`; human reads, empty reads and claims do not count. Migration 089 (`onboarding_tests`). `POST /v1/projects/:id/test-event` is unchanged.

### POST /v1/alerts/preview

Console user authentication and organization membership required; agent PATs are
not accepted. Body: projectId (UUID), eventType (new_bug, regression,
recommended_bug or status_change), title (at most1,000 characters), severity
(low/medium/high/critical), optional url (at most4,096) and userEmail (at most254).
Unknown fields are rejected. This evaluates saved alert rules at checkedAt,
without creating policies, captures, batches or deliveries and without calling
connections. Auto-ignore rules apply earlier during capture.

The response contains projectGate, caller-only email disposition and up to100
connection decisions, plus totalDestinations. Connection configuration and
recipient addresses are omitted. Email distinguishes immediate eligibility,
digest retention and exclusion. Eligible connections are not credential tests.
New-bug and regression connections return `deferred` during quiet hours when otherwise eligible. Digest exclusions remain `not_scheduled`. Quiet-hour status-change samples report `capture_path_only`: capture promotions use durable delivery, while manual/legacy changes can be suppressed.
Membership and preferences are rechecked at real delivery.


## Evidence capability discovery

`GET /v1/evidence/capabilities` accepts one current human JWT, scoped agent PAT, or capture key through the existing evidence authentication. The response is private/no-store. It returns `schemaVersion:1`, `configured`, `formats` (kind/contentType/maxBytes), and `reason`. Capture keys also receive their authenticated `projectId`; request parameters cannot select another owner. An unconfigured runtime returns false, an empty list, and `storage_unavailable`. Configuration is not proof of storage reachability, quota or transfer completion.

Current admitted formats are `log`/`text/plain` (1MiB) and `replay`/`application/json` (10MiB) when storage is configured. Image/audio are unavailable. The browser SDK disables built-in screenshot/voice actions until artifact delivery is implemented; custom onSubmit integrations own their media. Old queued media is retained under its original TTL and reports `onQueueEvent` state `unavailable`, reason `media-unavailable`; it is not acknowledged as delivered.


### Occurrence file metadata

`GET /v1/evidence/projects/:projectId/occurrences/:occurrenceId/artifacts?limit=20&offset=0` lists files for one occurrence. It returns `{ artifacts, total, limit, offset }`, ordered by creation time then ID, ascending. The limit is 1–100 and offset 0–10000. Each item includes artifact/project/occurrence IDs, format, byte count, SHA-256, state, generation, creation/expiry times and the client redaction declaration. Storage keys, storage credentials and uploader IDs are never returned.

Current human membership or a PAT with `get_repro_context` and a current project grant is required. Capture keys cannot list or download files. Missing/foreign occurrences return 404 after project authorization; unauthorized projects return 403. Unconfigured storage returns 503. A client redaction declaration is not independent proof that private information was removed.

The console previews ready PNG screenshots through bounded authenticated downloads and an exact byte/hash check. Pending, failed, expired and missing files are explicit. Logout, workspace/occurrence changes, expiry and unmount remove the old image. This does not enable built-in screenshot uploads or hosted image admission: hosted policy remains unchanged until storage and decoder qualification are complete.

## Managed installation delivery receipt

Human admin/manager JWT sessions can enroll an application with `POST /v1/applications/projects/:projectId` (`requestId`, `name`, `identifier`), then an installation with `POST /v1/applications/projects/:projectId/:applicationId/installations` (`requestId`, optional `label`). Keep each request ID and body fixed across uncertain retries. Matching list routes return bounded cursor pages. Capture keys and agent PATs cannot enroll or read this registry.

`GET /v1/applications/projects/:projectId/:applicationId/installations/:installationId/capture-status` accepts only the scoped path; no query/body options. It checks current manager membership and returns a non-cacheable `waiting` or `capture_received` state with `checkedAt` and nullable `firstCapture`. A first capture contains `captureId`, `occurrenceId`, the current canonical `bugId` when evidence exists, `acceptedAt`, `sdkName`, `sdkVersion`, `captureSource`, `platform` and `evidenceAvailability` (`available` or `deleted_or_expired`). A failed/denied check must not become a waiting or successful state.

Only a newly accepted v1 capture with exact managed application/installation identity creates this immutable receipt. Supported combinations are browser `@bugtape/sdk`, platform `web`, source `automatic` or `user_report`; or `bugtape-swift`, framework `native`, runtime `swift`, source `handled_error` or `user_report`, and the paired platform/OS values `ios`/`ios` or `other`/`macos`. Swift receipts also retain `osFamily`, `framework` and `runtime`. The receipt commits with ingest. Fatal native capture is excluded. The browser Setup flow still verifies browser installation only; this API does not complete native Setup. Console samples, legacy NULL sources, another installation and old accepted-capture retries do not qualify. No client timestamp determines freshness, and no historical data is backfilled. Capture-key clients can assert these provenance fields, so a receipt proves accepted delivery rather than device or binary attestation. Evidence deletion preserves minimal receipt identifiers; installation/project deletion cascades them.

Native receipt creation additionally requires `BUGTAPE_NATIVE_INSTALLATION_RECEIPTS_ENABLED=true` in the server runtime. The default is off for staged deployment. Disabling it stops new native receipts but preserves truthful reads of existing receipts. Reports remain ingestible, and no receipt is created retroactively when the flag is enabled.

### Occurrence capture provenance

`GET /v1/bugs/:id/occurrences` includes optional `sdk_name`, `sdk_version` and `capture_source` on each stored occurrence. Setup uses these with the project, platform and capture time to verify an app report. Old records can have null or missing provenance. A console sample or imported report does not verify SDK installation.

Connection delivery history keeps its default date-ascending order. `GET /v1/integrations/:id/deliveries?status=success&limit=1&order=desc` selects the latest successful receipt. Setup requires a receipt admitted at or after the connection’s last configuration change.