Server Ingest API

Server-side event and error ingest for BugWatch. Uses x-api-key with ingest:write scope. Also includes the browser-session mint endpoint (called server-side to produce a token for the browser).

Scope required: ingest:write

Event severity scale trace=10 · debug=20 · info=30 · warn=40 · error=50 · fatal=60

Event payload contract

Field	Type	Notes
`level`	number	string
`time`	number	Epoch milliseconds - optional; server stamps now if omitted
`message`	string	Human-readable description
`release`	string ≤200	Build/version label - informational in the body; the real environment binding comes from your API key
`environment`	string	Informational only; the actual environment is bound to the API key
`eventId`	string	Optional; enables deduplication within a 10-minute window
`traceId`	hex string ≤32	Distributed trace id
`spanId`	hex string ≤16	Span id
`tags`	flat object	Scalar string values only; max 50 keys
`user`	object	Accepted keys: `id`, `email`, `username`, `ip` - any other key is silently dropped
`exception`	object	`{type, value, stacktrace: {frames: [{filename, function, lineno, colno}]}}`
`breadcrumbs`	array	Leading context events
`context`	object	Arbitrary structured data - passed through and redacted
`fingerprint`	string or string[]	Optional grouping override (controls how events group into issues)

Producing this from your app: user (global vs concurrency-safe per-request vs per-capture), tags, release, context and trace IDs are set through the BugWatch SDKs - see SDK Usage & Event Enrichment. On the wire each event carries a single merged user object; there is no separate per-request-user field.

POST/api/v1/bugwatch/browser-sessionMint browser session token

Mint browser session token

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

Headers

x-api-key

Responses

200 – Token minted

{
  "token": "eyJhbGciOiJIUzI1NiJ9.example",
  "expiresAt": "2026-06-26T12:15:00.000Z"
}

boltTry it

env

POSThttps://api.newinstance.cloud/api/v1/bugwatch/browser-session

Headers

x-api-key

Request body

Code samples

curl -X POST 'https://api.newinstance.cloud/api/v1/bugwatch/browser-session'

POST/api/v1/bugwatch/ingestIngest – log event (JSON)

Ingest – log event (JSON)

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

Field	Type	Notes
`level`	number	`10/20/30/40/50/60`
`time`	number	Unix ms timestamp
`message`	string	Human-readable text
`release`	string	App build version
`environment`	string	`production` / `staging` / `development`
`eventId`	string	Optional; enables deduplication within 10-min window
`tags`	object	Flat key-value labels (≤50 keys)
`user`	object	`{id, email, username, ip}` - only these four keys; others are silently dropped
`traceId`	string	Hex distributed trace id (≤32 chars)
`spanId`	string	Span id
`exception`	object	`{type, value, stacktrace: {frames}}`
`breadcrumbs`	array	Leading events

Success - 202 Accepted

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

Headers

x-api-key

Request body

application/json

{
  "level": 30,
  "time": {{nowMs}},
  "message": "User signed in",
  "release": "1.0.0",
  "environment": "production",
  "tags": { "region": "eu-west-1" },
  "user": { "id": "usr_123", "email": "alice@example.com" }
}

Responses

Successful response

null

boltTry it

env

POSThttps://api.newinstance.cloud/api/v1/bugwatch/ingest

Headers

x-api-key

Request body

{
  "level": 30,
  "time": {{nowMs}},
  "message": "User signed in",
  "release": "1.0.0",
  "environment": "production",
  "tags": { "region": "eu-west-1" },
  "user": { "id": "usr_123", "email": "alice@example.com" }
}

Code samples

curl -X POST 'https://api.newinstance.cloud/api/v1/bugwatch/ingest' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "level": 30,
  "time": {{nowMs}},
  "message": "User signed in",
  "release": "1.0.0",
  "environment": "production",
  "tags": { "region": "eu-west-1" },
  "user": { "id": "usr_123", "email": "alice@example.com" }
}'

arrow_back

Browser Ingest

OpenTelemetry, Prometheus & Tracing

arrow_forward