Verify that your API key is valid and inspect its metadata.

Run this first after generating a key to confirm it is active and check the environment (test vs live).

Authentication

• Header: x-api-key: {{apiKey}}

Success — 200 OK

{
  "success": true,
  "message": "API key is valid",
  "business": { "id": "org_abc123", "name": "Acme Corp", "slug": "acme-corp" },
  "key": { "id": "sk_test_abc123", "environment": "test" },
  "timestamp": "2026-06-26T10:00:00.000Z"
}

Common errors

• 401 — key missing, malformed, or revoked
• 403 — key found but inactive

Mint a short-lived browser session token. Call this from your backend using the secret key — the token is then passed to your frontend. The secret never reaches the client.

Scope: ingest:write

Request

• Method: POST
• Header: x-api-key: {{apiKey}}
• Body: empty

Success — 200 OK

{ "token": "<session-token>", "expiresAt": "2026-06-26T12:15:00.000Z" }

Common errors

• 401 — invalid/missing x-api-key
• 403 — key lacks ingest:write scope

Ingest logs and error events from server-side or CI environments.

Scope: ingest:write

Request

• Header: x-api-key: {{apiKey}}
• Content-Type: application/json (single object or array) or application/x-ndjson (one event per line)
• Max body: 2 MB

Event fields

Success — 202 Accepted

{ "ingested": 1, "skipped": 0, "deduped": 0 }

Ingest events from browser / SPA applications.

Authentication: x-bugwatch-session — a short-lived token minted by your backend via POST /api/v1/bugwatch/browser-session. Run "Mint browser session token" first; the test script saves it as {{sessionToken}} automatically.

The secret key never reaches the browser. The session token is ingest-only, scoped to one project+environment, and honours the project's allowedOrigins allow-list.

Request

• Header: x-bugwatch-session: {{sessionToken}}
• Content-Type: application/json or application/x-ndjson
• Max body: 2 MB
• CORS: allowed from any origin in the project's allowedOrigins (empty = allow all)

Success — 202 Accepted

{ "ingested": 1, "skipped": 0, "deduped": 0 }

Common errors

• 401 — invalid or expired session token
• 403 — origin not in allowedOrigins (origin_not_allowed)
• 404 — project not found or inactive

Ingest events from native mobile apps (iOS, Android, Flutter, React Native).

Authentication: x-bugwatch-token — a client-signed token built on device by the SDK. The app embeds a per-project mobileAppSecret (HKDF-derived), signs each request locally, and sends only the signed token. The secret is never transmitted.

The pre-request script on this request reproduces the exact token the SDK builds using CryptoJS. Set projectId, environment, and mobileAppSecret in your environment before running.

Token format: base64url(claims).base64url(HMAC-SHA256(claims, appSecret))

Claims (deterministic key order, no spaces):

{"pid":"<projectId>","env":"<env>","iat":<nowSec>,"exp":<nowSec+300>,"nonce":"<16 hex chars>"}

Request

• Header: x-bugwatch-token: {{mobileToken}} (auto-built by pre-request script)
• Content-Type: application/json or application/x-ndjson
• Max body: 2 MB
• Rate limit: 12,000 events / 60 seconds per project

Success — 202 Accepted

{ "ingested": 1, "skipped": 0, "deduped": 0 }

Common errors

• 401 — invalid/expired/malformed token
• 429 — rate limited

Event model (what each SDK puts on the wire)

One merged event per request (eventId, time, level required). The four native SDKs share this endpoint:

• Native crashes (iOS, Android NDK) carry payloadVersion: 2 with top-level binaryImages + nativeStacktrace (iOS) / nativeFrames (Android) — raw instruction_addr values the worker symbolicates against the uploaded dSYM / ELF by UUID / build-id.
• JVM / Dart / JS exceptions (Android, Flutter, React Native) and handled errors carry exception.stacktrace as an array of { filename, function, lineno, colno, in_app } frames — de-obfuscated server-side via the uploaded R8 mapping / dart-symbols / source map.
• All SDKs also emit ANR / app-hang, message, and release-health session events through this same endpoint.

See the per-platform examples in this folder — iOS native crash, Android JVM, Android NDK, Flutter, React Native — and the matching upload in 4 · Source Maps & Symbols.

Step 1 of 2 — request a presigned URL for a text symbolication artifact.

Scope: symbols:upload · Auth: project secret key (keyId:secret)

The file never passes through this API. You presign, PUT the bytes straight to storage, then confirm. That is why uploads are not bound by request-size limits — the previous raw-body routes were rejected by the edge proxy for any real symbol file.

1. POST  …/presign                       → { uploadId, uploadUrl, expiresAt }
2. PUT   <uploadUrl>                      → the raw bytes, streamed to storage
3. POST  …/uploads/{uploadId}/complete    → verified, then queued

The API key goes on steps 1 and 3 only — never to the storage host, which is authorised by the presigned URL's own signature.

Uploads are idempotent per (release, platform, artifactType) — completing a new upload replaces the previous artifact and deletes the superseded file.

The release you declare must match the release your SDK reports at runtime, or the artifact exists but nothing matches it and stacks stay unreadable.

Most integrators should use the CLI, which performs all three steps, streams the file (flat memory regardless of size) and retries transient failures:

# Binary debug-symbol archives — Apple dSYM, Android native .so
npx @newinstance/bugwatch-cli symbols upload MyApp.xcarchive \
  --release "1.4.2" --build-number "318"

# Text artifacts — R8/ProGuard mapping, source map, Dart symbols
npx @newinstance/bugwatch-cli artifacts upload mapping.txt \
  --release "1.4.2" --platform android --type r8

The two commands are not interchangeable: symbols upload accepts binary archives only and validates magic bytes, so a mapping.txt or .map is rejected.

Step 2 of 2 — confirm the artifact landed and swap it in.

Scope: symbols:upload

What is verified

• complete confirms the object actually landed in storage and that its size matches what was declared at presign.
• The pending row is looked up scoped to the calling project, so one project can never finalise another's upload (a miss returns 404).
• Only an AWAITING_UPLOAD row can be completed, so a completion cannot be replayed to re-queue processing.
• For debug symbols the worker re-hashes the real bytes before indexing and rejects a mismatch (CHECKSUM_MISMATCH). A declared checksum is never trusted on its own.

Responses

• 201 { fileId, sha256 } — stored and now the active artifact for that (release, platform, artifactType).
• 409 — the object was never PUT to uploadUrl.
• 400 — the stored size does not match what was declared at presign.
• 404 — no such upload for this project.

Step 1 of 2 — request a presigned URL for a binary debug-symbol archive.

Scope: symbols:upload · Auth: project secret key (keyId:secret)

The file never passes through this API. You presign, PUT the bytes straight to storage, then confirm. That is why uploads are not bound by request-size limits — the previous raw-body routes were rejected by the edge proxy for any real symbol file.

1. POST  …/presign                       → { uploadId, uploadUrl, expiresAt }
2. PUT   <uploadUrl>                      → the raw bytes, streamed to storage
3. POST  …/uploads/{uploadId}/complete    → verified, then queued

The API key goes on steps 1 and 3 only — never to the storage host, which is authorised by the presigned URL's own signature.

Matching is by debug UUID / build-id, not by release name — the identifier embedded in the binary. That is why an upload from any build machine resolves crashes from any device running that exact binary, and why release here is metadata for search rather than the match key. (Source maps and mappings are the opposite: those match on release + platform.)

Declaring a sha256 that already exists for this project short-circuits as a duplicate and returns no uploadUrl — the transfer is skipped entirely.

Most integrators should use the CLI, which performs all three steps, streams the file (flat memory regardless of size) and retries transient failures:

# Binary debug-symbol archives — Apple dSYM, Android native .so
npx @newinstance/bugwatch-cli symbols upload MyApp.xcarchive \
  --release "1.4.2" --build-number "318"

# Text artifacts — R8/ProGuard mapping, source map, Dart symbols
npx @newinstance/bugwatch-cli artifacts upload mapping.txt \
  --release "1.4.2" --platform android --type r8

The two commands are not interchangeable: symbols upload accepts binary archives only and validates magic bytes, so a mapping.txt or .map is rejected.

Step 2 of 2 — confirm the archive landed and queue it for indexing.

Scope: symbols:upload

What is verified

• complete confirms the object actually landed in storage and that its size matches what was declared at presign.
• The pending row is looked up scoped to the calling project, so one project can never finalise another's upload (a miss returns 404).
• Only an AWAITING_UPLOAD row can be completed, so a completion cannot be replayed to re-queue processing.
• For debug symbols the worker re-hashes the real bytes before indexing and rejects a mismatch (CHECKSUM_MISMATCH). A declared checksum is never trusted on its own.

Archive-type validation happens in the worker, not here, because this API never sees the bytes. An archive that is not a zip / Mach-O / ELF lands as INVALID with UNRECOGNIZED_ARCHIVE; an ELF declared under an Apple platform fails with ARCHIVE_PLATFORM_MISMATCH.

Responses

• 200 { uploadId, status: "QUEUED" } — accepted; poll Get upload status for indexing progress.
• 409 — the archive was never PUT to uploadUrl.
• 400 — declared size does not match the stored object.

List recent debug symbol uploads for this project, newest first.

Scope: symbols:read

Query params

• limit (optional, int 1–200, default 50)
• status (optional, string) — filter by QUEUED | PROCESSING | DONE | FAILED

Success — 200 OK returns { uploads: [...] }

Trigger re-symbolication for crashes that arrived before symbols were uploaded.

Scope: symbols:reprocess

Previously-unsymbolicated crashes are then re-processed with the newly-uploaded symbols.

Body: empty

Success — 200 OK

{ "requeued": 12 }

Send OpenTelemetry logs to BugWatch via OTLP/HTTP.

Scope: ingest:write

Content-Type options

• application/json — JSON body (used here)
• application/x-protobuf — protobuf ExportLogsServiceRequest (used by the OTel Collector)

Request body (JSON form)

{
  "resourceLogs": [{
    "resource": { "attributes": [{ "key": "service.name", "value": { "stringValue": "my-service" } }] },
    "scopeLogs": [{
      "logRecords": [{
        "timeUnixNano": "1750924800000000000",
        "severityNumber": 9,
        "severityText": "INFO",
        "body": { "stringValue": "User signed in" },
        "attributes": [{ "key": "user.id", "value": { "stringValue": "usr_123" } }]
      }]
    }]
  }]
}

Success — 200 OK (empty body on full success)

{}

On partial rejection:

{ "partialSuccess": { "rejectedLogRecords": 2, "errorMessage": "some records rejected" } }

Send OpenTelemetry traces to BugWatch via OTLP/HTTP.

Scope: ingest:write

Content-Type options

• application/json — JSON body (used here)
• application/x-protobuf — protobuf ExportTraceServiceRequest (used by the OTel Collector)

Request body (JSON form)

{
  "resourceSpans": [{
    "resource": { "attributes": [{ "key": "service.name", "value": { "stringValue": "my-service" } }] },
    "scopeSpans": [{
      "spans": [{
        "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
        "spanId": "00f067aa0ba902b7",
        "name": "HTTP GET /api/users",
        "kind": 2,
        "startTimeUnixNano": "1750924800000000000",
        "endTimeUnixNano": "1750924800050000000",
        "status": { "code": 1 }
      }]
    }]
  }]
}

Success — 200 OK (empty body on full success; partialSuccess on rejection)

Send OpenTelemetry metrics to BugWatch via OTLP/HTTP.

Scope: ingest:write

Content-Type options

• application/json — JSON body (used here)
• application/x-protobuf — protobuf ExportMetricsServiceRequest (used by the OTel Collector)

Request body (JSON form)

{
  "resourceMetrics": [{
    "resource": { "attributes": [{ "key": "service.name", "value": { "stringValue": "my-service" } }] },
    "scopeMetrics": [{
      "metrics": [{
        "name": "http.server.request.duration",
        "unit": "ms",
        "gauge": {
          "dataPoints": [{
            "timeUnixNano": "1750924800000000000",
            "asDouble": 123.4,
            "attributes": [{ "key": "http.method", "value": { "stringValue": "GET" } }]
          }]
        }
      }]
    }]
  }]
}

Success — 200 OK (empty on full success; partialSuccess on rejection)

Prometheus remote-write ingestion endpoint.

Scope: ingest:write

This endpoint is NOT called directly by humans. It is invoked by the Prometheus remote-write adapter or the bugwatch-otel-collector. The body is a Snappy-compressed protobuf WriteRequest — you cannot send a readable JSON body here.

To use Prometheus remote-write with BugWatch:

1. Deploy the bugwatch-otel-collector (or configure Prometheus remote_write)
2. Set the remote-write URL to: {{baseUrl}}/api/v1/prom/write
3. Add header: x-api-key: sk_live_KEYID:secret

Success — 204 No Content

Common errors

• 400 — malformed Snappy/protobuf body
• 401 — invalid API key
• 429 — rate limited

Query stored Prometheus metrics using a PromQL-compatible selector.

Scope: ingest:write (same key used for write is accepted for query)

Query params

• query (required) — metric name or label selector e.g. http_requests_total or {service="api-gateway"}
• time (optional) — Unix timestamp (seconds, float); defaults to now

Success — 200 OK

{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [{ "metric": { "__name__": "http_requests_total", "service": "api" }, "value": [1750924800, "42"] }]
  }
}

Query stored Prometheus metrics over a time range.

Scope: ingest:write

Query params

• query (required) — metric selector
• start (required) — range start as Unix seconds (float)
• end (required) — range end as Unix seconds (float)

Success — 200 OK

{
  "status": "success",
  "data": {
    "resultType": "matrix",
    "result": [{ "metric": { "__name__": "http_requests_total" }, "values": [[1750924800, "42"], [1750924860, "47"]] }]
  }
}

List all distinct metric names stored for this project+environment.

Scope: ingest:write

Success — 200 OK

{ "status": "success", "data": ["http_requests_total", "rum.lcp", "rum.cls"] }

List distinct service names that have sent traces to this BugWatch project.

Scope: ingest:write (same API key)

Success — 200 OK

{ "data": ["api-gateway", "payment-service", "user-service"], "total": 3, "limit": 3, "offset": 0, "errors": null }

List recent distributed traces for this project+environment.

Scope: ingest:write

Query params

• service (optional) — filter by service name
• limit (optional, default 20, max 100)
• lookback (optional) — 1h | 24h | 7d | 30d (default 1h)

Success — 200 OK — returns Jaeger-compatible trace list with spans.

Ingest Real User Monitoring (RUM) web-vitals metrics (LCP, CLS, INP, FID, TTFB).

Auth: Either x-bugwatch-session (browser) or x-api-key (server-side / testing)

Scope (for x-api-key): ingest:write

Request body — three accepted shapes:

1. Wrapped array:

{ "vitals": [{ "name": "LCP", "value": 1250.5, "url": "https://example.com/", "rating": "good" }] }

1. Bare array:

[{ "name": "CLS", "value": 0.05, "rating": "good" }, { "name": "INP", "value": 180, "rating": "needs-improvement" }]

1. Single vital object:

{ "name": "TTFB", "value": 320, "url": "https://example.com/checkout", "rating": "needs-improvement" }

Vital field schema:

Success — 202 Accepted

{ "ingested": 2 }

Stored as rum.<name_lower> metric points (e.g. rum.lcp, rum.cls).

Common errors

• 400 — malformed JSON
• 401 — invalid session token or API key
• 403 — origin not in allowedOrigins (when using session token)
• 429 — rate limited

Mint a single-use support-portal sign-in link for a customer your backend has already authenticated.

Returns a URL that signs the customer into the support portal without a password. The link expires in 10 minutes and is single-use.

Scope: full-access or ticket-management

Request body

Success — 200 OK

{ "url": "https://support.yourcompany.com/auth/redeem?token=abc123", "expiresAt": "2026-06-26T10:10:00.000Z" }

List tickets for a customer, identified by email.

Scope: full-access or ticket-management or read-only

Query params

Success — 200 OK returns paginated ticket list.

Create a support ticket on behalf of a customer. Auto-creates the customer record if not found.

Scope: full-access or ticket-management

Request body

Success — 201 Created

{ "ticketId": "tkt_abc123", "status": "OPEN", "createdAt": "2026-06-26T10:00:00.000Z" }

The test script saves ticketId to the environment automatically.

Add a public comment from the customer to a ticket.

Scope: full-access or ticket-management

Side effects:

• Auto-reopens RESOLVED tickets to IN_PROGRESS
• Cannot comment on CLOSED tickets (returns 422)

Path param: ticketId (auto-filled from environment)

Request body

Success — 201 Created

{ "commentId": "cmt_abc123", "createdAt": "2026-06-26T10:05:00.000Z" }

Fetch the encrypted Master Encryption Key (MEK) for an app.

Scope: full-access or secret-read

Path param: appId — the App ID from the secret manager dashboard (set as {{appId}} in your environment)

Success — 200 OK

{
  "encryptedMek": "<base64-encoded-encrypted-key>",
  "algorithm": "AES-256-GCM",
  "kdfAlgorithm": "HKDF-SHA256"
}

Decrypt the MEK using your App Secret:

const mek = await crypto.subtle.decrypt(
  { name: 'AES-GCM', iv: decodeBase64(iv) },
  await deriveKey(appSecret),  // HKDF-SHA256
  decodeBase64(encryptedMek)
);

Common errors

• 401 — invalid API key
• 403 — key lacks secret-read scope
• 404 — app not found
• 429 — rate limited (50 req/hour)

Fetch encrypted environment variables for an app.

Scope: full-access or secret-read

Path param: appId — App ID from dashboard Query param: environment (optional) — development | staging | production (default: development)

Success — 200 OK

{
  "environment": "production",
  "variables": [
    { "key": "DATABASE_URL", "encryptedValue": "<base64>", "iv": "<base64>" },
    { "key": "STRIPE_SECRET_KEY", "encryptedValue": "<base64>", "iv": "<base64>" }
  ]
}

Decrypt each variable using the MEK from GET master-key:

const plaintext = await crypto.subtle.decrypt(
  { name: 'AES-GCM', iv: decodeBase64(variable.iv) },
  mek,
  decodeBase64(variable.encryptedValue)
);

Common errors

• 401 — invalid API key
• 403 — key lacks secret-read scope
• 404 — app not found or no variables for this environment