BugTape docs

API Reference

Every public endpoint.

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

All endpoints are prefixed with /v1/.

Authentication

The API uses these authentication modes:

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

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

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:

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

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

{
  "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:

{ "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:

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

Malformed JSON bodies return:

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

Plan-limit violations return HTTP 402:

{
  "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):

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

Degraded (503):

{
  "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:

{
  "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):

{
  "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:

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

Success (201):

{
  "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:

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

Success (200):

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

Error codes:

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:

{ "refreshToken": "eyJ..." }

Success (200):

{ "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):

{
  "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:

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

Success (200):

{ "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:

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

Success (200):

{ "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):

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

Or, if already verified:

{ "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:

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

Success (200):

{
  "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:

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

Success (200):

{ "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):

{
  "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.

Request headers

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

Request body

{
  // 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

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

Success response (201)

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

Error responses

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:

{
  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):

{ "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:

{
  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):

{
  "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:

Success (200):

{
  "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):

{
  "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):

{
  "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):

{
  "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:

JSON success (200):

{
  "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):

{
  "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):

{
  "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.

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):

{
  "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):

{
  "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):

{ "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):

{
  "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):

{
  "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):

{
  "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:

{
  "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):

{ "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:

{
  "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):

{ "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:

{
  "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):

{ "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:

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

Success (201):

{
  "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:

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

Success (200):

{ "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):

{ "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):

{
  "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):

{ "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):

{
  "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:

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

orgId must match the caller's org.

Success (201):

{ "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:

{ "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):

{
  "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):

{
  "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):

{ "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):

{
  "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:

{
  "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):

{ "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:

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

Success (200):

{
  "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):

{ "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):

{
  "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):

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

Success (200):

{ "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):

{
  "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.

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):

{
  "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:

{
  "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.

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):

{
  "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:

{
  "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):

{
  "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.

{
  "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.

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 and 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):

{
  "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):

{
  "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):

{
  "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):

{
  "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:

{
  "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):

{
  "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:

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{ "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):

{
  "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):

{
  "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):

{
  "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

Auth

Ingestion

Bugs (read)

Bugs (write)

Projects & API keys

Team

Org usage

Notifications

Integrations

Admin (superadmin only)

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.

{ "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.

{ "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.

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

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)

Billing

Portfolio

Bugs — grouping and search

Auth — account lifecycle and GDPR

Admin — maintenance

Health

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.

{
  "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.

{
  "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.