NewInstance

Checks that your API key is valid and returns the organization it belongs to and its environment.

Run this first after generating a key to confirm it is active and to see whether it is a test or a live key. A malformed or revoked key is refused the same way as a missing one.

Sends a browser event authenticated with a session token minted by Server Ingest API → Mint browser session token (run that request first: it stores sessionToken). The payload contract is the same as server ingest. The browser's Origin header is checked against the project's allowed origins. When the token expires, the SDK mints a new one automatically.

Mints a short-lived browser session token. Call this from your backend with the secret key, then pass the token to your frontend. The secret never reaches the client.

Scope: ingest:write

Send the request with an empty body.

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

Scope: ingest:write

Send Content-Type: application/json with a single event or an array of events, or application/x-ndjson with one event per line. The body can be up to 2 MB.

Event fieldslink

Send an error eventlink

Set level to 50 and add exception, breadcrumbs and trace ids. The eventId enables deduplication: re-sending the same event within 10 minutes increments deduped instead of ingested, as the duplicate example response shows.

{
  "level": 50,
  "time": {{nowMs}},
  "message": "Uncaught TypeError: Cannot read properties of undefined",
  "release": "{{release}}",
  "environment": "{{environment}}",
  "eventId": "evt_unique_abc123",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "spanId": "00f067aa0ba902b7",
  "contexts": { "cart": { "id": "cart_42", "items": 3 } },
  "tags": { "component": "checkout" },
  "user": { "id": "usr_456", "username": "alice" },
  "exception": {
    "type": "TypeError",
    "value": "Cannot read properties of undefined (reading 'price')",
    "stacktrace": {
      "frames": [
        { "filename": "checkout.js", "function": "calculateTotal", "lineno": 42, "colno": 15 },
        { "filename": "cart.js", "function": "applyDiscount", "lineno": 88, "colno": 7 }
      ]
    }
  },
  "breadcrumbs": [
    { "timestamp": {{nowMs}}, "category": "navigation", "message": "Navigated to /checkout", "level": "info" },
    { "timestamp": {{nowMs}}, "category": "ui.click", "message": "Clicked \"Apply coupon\"", "level": "info" }
  ]
}

Send a batch as NDJSONlink

Set Content-Type: application/x-ndjson and put one event on each line. Each line is an independent event. This is the preferred format for batching from server SDKs.

{"level":50,"time":{{nowMs}},"message":"Payment processing failed","release":"{{release}}","environment":"{{environment}}","tags":{"orderId":"ord_789"},"user":{"id":"usr_789"}}
{"level":30,"time":{{nowMs}},"message":"Retry attempt 1 of 3","release":"{{release}}","environment":"{{environment}}","tags":{"orderId":"ord_789"}}

Sends OpenTelemetry logs to BugWatch over OTLP/HTTP.

Scope: ingest:write

Send application/json, as in this example, or application/x-protobuf with a protobuf ExportLogsServiceRequest, which is what the OTel Collector sends. A fully accepted batch answers with an empty {} object.

Sends OpenTelemetry traces to BugWatch over OTLP/HTTP.

Scope: ingest:write

Send application/json, as in this example, or application/x-protobuf with a protobuf ExportTraceServiceRequest, which is what the OTel Collector sends. A fully accepted batch answers with an empty {} object.

Sends OpenTelemetry metrics to BugWatch over OTLP/HTTP.

Scope: ingest:write

Send application/json, as in this example, or application/x-protobuf with a protobuf ExportMetricsServiceRequest, which is what the OTel Collector sends. A fully accepted batch answers with an empty {} object.

Receives Prometheus remote-write samples.

Scope: ingest:write

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 the header x-api-key: sk_live_KEYID:secret.

Returns the latest value of each matching metric series at one point in time, using a PromQL-compatible selector.

Scope: ingest:write (the key you write with is accepted for queries)

The same query also works as a POST with form-encoded parameters, which is what Grafana's Prometheus data source sends.

Returns every stored point of each matching metric series over a time range.

Scope: ingest:write

The same query also works as a POST with form-encoded parameters, which is what Grafana's Prometheus data source sends.

Lists every distinct metric name stored for the project and environment your key is scoped to.

Scope: ingest:write

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

Scope: ingest:write (the same API key)

Lists recent distributed traces for the project and environment your key is scoped to, newest first, each with its spans in the Jaeger format.

Scope: ingest:write

Returns every span of one trace in the Jaeger format.

Scope: ingest:write

traceId in the path is the 32-character hex trace identifier, as sent in traceparent or returned by Jaeger – list traces. A trace id with no stored spans answers 200 with an empty data list, not 404.

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

Authenticate with x-bugwatch-session from a browser, or with x-api-key from a server or while testing.

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

Request body: three shapes are accepted.

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:

Vitals are stored as rum.<name_lower> metric points (for example rum.lcp, rum.cls). A browser call from an origin outside the project's allowed origins is refused with 401, the same as a bad session token.

Requests a presigned URL for a text symbolication artifact. This is step 1 of 2.

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

Confirms the artifact landed in storage and makes it the active artifact for its (release, platform, artifactType). This is step 2 of 2.

Scope: symbols:upload

uploadId in the path is the id returned by step 1, the presign request.

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 finalize 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. Completing it again answers 200 with alreadyCompleted: true.
• 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.

Requests a presigned URL for a binary debug-symbol archive. This is step 1 of 2.

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 authorized by the presigned URL's own signature.

Matching is by debug UUID / build-id, the identifier embedded in the binary, not by release name. 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, so 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.

Confirms the archive landed in storage and queues it for indexing. This is step 2 of 2.

Scope: symbols:upload

uploadId in the path is the id returned by step 1, the presign request. After this call, poll Get upload status for indexing progress.

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 finalize 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. Completing it again answers 200 with alreadyCompleted: true.
• 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.

Lists this project's recent debug symbol uploads, newest first.

Scope: symbols:read

Returns the processing status and indexing summary of one debug symbol upload.

Scope: symbols:read

uploadId in the path comes from the presign response.

Status flow: QUEUED, then EXTRACTING, then one of AVAILABLE, PARTIALLY_AVAILABLE (some objects were invalid), INVALID or FAILED.

Poll this until status is AVAILABLE or PARTIALLY_AVAILABLE before relying on symbolication.

Re-symbolicates crashes that arrived before this upload's symbols did.

Scope: symbols:reprocess

uploadId in the path is the debug symbol upload the waiting crashes need. Crashes still waiting for its symbols, or only partly symbolicated, are queued again and processed with them. Send an empty body.

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

Scope: deploy:write

Every field is optional, and an empty body is valid.

Keep the returned id: every later call needs it. The status starts as in_progress. A 404 means the project bound to this key no longer exists.

Updates a deployment with a stage transition, a finish or an explicit failure. The body carries one of stage, finish or fail.

Scope: deploy:write

deployId in the path is the id returned by Start deployment. Only a key for the same project can update it; any other key gets 404.

1. Stage transition

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

status is running, succeeded or failed; exitCode and errorSummary are optional. Repeat per stage. A stage key is upserted, so 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" } }

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

Streams a batch of log lines for one stage. Call it 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

deployId in the path is the id returned by Start deployment.

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, so do not add them yourself. Lines land in the project's normal log search.

truncated: true means the per-deployment log cap was reached; further batches are dropped, while finish and fail still work.

Mints 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

Lists one customer's tickets, page by page. The customer is identified by email.

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

Creates a support ticket on behalf of a customer, and creates the customer record if it does not exist yet.

Scope: full-access or ticket-management

Request body

The returned ticketId is what the detail and comment endpoints take.

Returns one ticket with its public, customer-facing comments.

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

ticketId in the path is the ticketId returned by Create ticket; Postman fills it in after that request runs. customerEmail must belong to the customer who owns the ticket: any other email answers 404, so one customer can never read another's ticket.

Adds a public comment from the customer to a ticket.

Scope: full-access or ticket-management

ticketId in the path is the ticketId returned by Create ticket; Postman fills it in after that request runs.

A comment on a RESOLVED ticket reopens it to OPEN. A CLOSED ticket takes no more comments.

Request body

Returns an app's Master Encryption Key (MEK), still encrypted under your App Secret.

Scope: full-access or secret-read

appId in the path is the App ID from the Secret Manager dashboard (set it as {{appId}} in your environment).

Unwrap encryptedMasterKey locally with your App Secret, using masterKeyIV and masterKeyTag (AES-256-GCM). The nismsdk package does this for you with decryptMasterKey. Each call counts toward your Secret Manager request allowance, and 429 means the allowance is used up under a hard limit.

Returns an app's environment variables for one environment, each value still encrypted under the app's MEK.

Scope: full-access or secret-read

appId in the path is the App ID from the Secret Manager dashboard.

Decrypt each value locally with the MEK from Get encrypted master key, using the variable's iv and tag (AES-256-GCM). The nismsdk package does this for you with decryptWithMasterKey. An environment with no variables answers 200 with an empty variables list.

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.

Returns the customer's live session, if they hold one.

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.

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

Invalidates whatever session a customer holds, for sign-out when you did not keep the session id.

Idempotent: when the customer holds no session it still returns 200 with revoked: false, because "this customer has no live chat session" is the desired end state either way. Wire it into your own sign-out and you never have to track session ids.

Reports whether this session has been invalidated.

chatSessionId in the path is the session.sessionId returned by Create a chat session; Postman stores it after that request runs.

Invalidation is the only thing a session id can answer, and the only thing worth asking. The token is a JWT: it carries its own exp and the customer's identity, so decode it for those. What the token cannot tell you is whether someone revoked it early, which is exactly what this reports.

revoked: false means no early invalidation was recorded. It does not mean the token is unexpired, because expiry is the token's business, not the platform's.

Invalidates a session before it expires.

chatSessionId in the path is the session.sessionId returned by Create a chat session.

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.