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

Send a browser event authenticated with a session token minted by Server Ingest API → Mint browser session token (run that request first: it stores sessionToken). Same payload contract as server ingest. The browser's Origin header is checked against the project's allowed origins: a mismatch returns 403 origin_not_allowed; an expired or invalid token returns 401 and the SDK re-mints automatically.

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 }

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

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 }

Create a deployment record. Call at the start of your CI deploy job.

Scope: deploy:write

Body (all fields optional - an empty body is valid)

• release - the release this deploy ships; should match what your SDK reports at runtime so errors correlate
• meta - string map: commit, repo, branch, triggeredBy

Success - 201 Created

{ "id": "dep_64fa3c9e2b7d41c8a9f01234" }

Keep the id: every later call needs it. Status starts as in_progress.

Common errors

• 401 - invalid/missing key
• 403 - key lacks deploy:write
• 404 - the project bound to this key no longer exists

Update a deployment. The body must contain exactly one of stage, finish, fail.

Scope: deploy:write

1 - Stage transition

{ "stage": { "key": "migrate", "name": "Run DB migrations", "status": "running" } }

status ∈ running | succeeded | failed; optional exitCode, errorSummary. Repeat per stage. A stage key is upserted - re-sending updates it.

2 - Finish

{ "finish": true }

Final status is derived from stages: any failed stage ⇒ failed, else succeeded. A failed finish opens a DeploymentFailure issue in the project.

3 - Fail explicitly

{ "fail": { "summary": "migrate exited 1", "stageKey": "migrate" } }

Success - 200 OK

{ "id": "dep_64fa3c9e2b7d41c8a9f01234", "status": "succeeded" }

Once status is no longer in_progress, further PATCHes are no-ops that echo the final status - safe to retry.

Common errors

• 400 - stage/log limits exceeded
• 404 - unknown deployment id (or wrong project's key)

Stream a batch of log lines for one stage. Call repeatedly while the stage runs - the CLI's deploy run does this for you from the wrapped command's stdout/stderr.

Scope: deploy:write · Max body: 2 MB per batch

Body: NDJSON (one JSON object per line) or a JSON array of { level, time, message }:

• level - Pino-style number: 10 trace · 20 debug · 30 info · 40 warn · 50 error · 60 fatal
• time - epoch milliseconds
• message - the log line

Deploy tags (deployId, stage) are injected server-side - do not add them yourself. Lines land in the project's normal log search.

Success - 202 Accepted

{ "ingested": 2, "skipped": 0, "deduped": 0, "truncated": false }

truncated: true means the per-deployment log cap was reached; further batches are dropped (finish/fail still work).

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 returned ticketId is what the detail and comment endpoints take.

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

The nism CLI (recommended for local dev and CI)link

The published CLI/SDK nismsdk (Node 18+, binaries nism and nismsdk) wraps the fetch + local-decrypt flow; plaintext never transits the platform.

npm i -g nismsdk        # or: npx nismsdk <command>

nism setup              # store appId / orgId / apiKey in ~/.nism/config.json
nism verify             # fetch, decrypt and confirm values are readable
nism load --environment production --create-env .env
eval "$(nism env --appSecret "$NISM_APP_SECRET" --format shell)" && node server.js

Commands: load (the default when no subcommand is given; flags include --environment, --create-env <file>, --env-set-name (default default) and --system-level), setup, config [--show-secrets], env (prints to stdout for piping; fish shells get set -gx), verify. nism does not wrap or spawn your process: to inject secrets into a command, eval the env output first as shown.

Credentials resolve in order: CLI flags, then NISM_* env vars, then legacy NEW_INSTANCE_* env vars, then ~/.nism/config.json, then an interactive prompt. The App Secret is never written to the config file: supply it per run or via NISM_APP_SECRET. Point at the live platform with NISM_GRAPHQL_URL=https://service.newinstance.cloud/service (the built-in default targets a local dev server, so production runs must set this).

Load flags (defaults): --environment development, --format dotenv|json|shell, --output <file>, --bridge true with --bridge-storage-dir ~/.nism, --shell-integration true (detects bash, zsh, fish, ksh, dash), --auto-add-to-profile, --ide-integration, --create-env [file] (a bare flag means .env), --silent, --debug.

Bridge files in ~/.nism: <environment>.json and ide.env at mode 0600, load-<environment>.sh at 0700, config.json at 0600. --auto-add-to-profile appends a marked source block to the matching shell profile. --create-env writes into the current directory with default permissions, unlike the 0600 bridge files, so gitignore the output.

CI: npx nismsdk load --silent --create-env .env with NISM_* repository secrets; add --no-bridge in Docker builds.

Programmatic use (same package): loadSecrets(), injectSecrets(), NismGraphQLClient, decryptMasterKey, decryptWithMasterKey.

Troubleshooting: an invalid App Secret fails the key check; "all variables failed to decrypt" means the right app but the wrong secret; authentication failures point at the API key or org; a missing inheritance link key surfaces when a linked app was unshared; ECONNREFUSED means the GraphQL URL is wrong or unreachable. Re-run with --debug.

Does this customer already hold a live session?

Call it before minting to decide whether to reuse the token you have, wait, or revoke and re-mint. A customer can hold at most one session, so sessions is a list of zero or one.

Expired and revoked sessions are simply absent: the record exists only while the session is usable.

Mint a chat session for one of your customers, from YOUR backend.

Call this wherever your app establishes a session - typically right after sign-in - and return the token to your frontend alongside your own session token. The frontend hands that one string to the chat SDK and passes nothing else.

Bodylink

One live session per customerlink

A customer may hold one session at a time. While theirs is still valid this returns 409 with the session that is in the way. Once it expires, or you revoke it, a new one can be minted. That keeps a single identity from accumulating parallel credentials.

The 409 body carries the existing session, so you can decide whether to keep using the token you already have or revoke and re-mint.

What comes backlink

A signed JWT, and a session summary that is only an id, its owner and its expiry.

Everything about the customer is inside the token, signed. The platform keeps no copy: it would be duplicated state that could drift from the claims, and the JWT already answers the question. If you need the name, email, phone or metadata back, decode the token.

The token is never stored either. If you lose it, revoke the session and mint another.

Kill a session before it expires.

The token stops being accepted on the next request: its signature is still valid and it has not expired, but the session is on the denylist. There is no propagation delay and no cache to wait out.

customerId is required so the customer's slot is freed as well as the token denied. Without it the token would die but the customer would stay blocked from a new session until natural expiry. You always have it: it is what you minted the session for.

Idempotent, so a retried sign-out is safe.

List the tools this key can use. Keys scoped to BugWatch (or FULL_ACCESS) see the three BugWatch tools; a key with no matching product scopes sees an empty list.

Response - result.tools[] with name, description and a JSON-Schema inputSchema per tool.