NewInstance Documentation

Browser Ingest

Send events from browsers and single-page apps. Browser code is public, so it never holds your secret key - your backend mints a short-lived session token (1 hour) and the browser sends events with x-bugwatch-session.

The flow

  1. Backend calls Server Ingest API → Mint browser session token with the secret DSN key.
  2. Your page fetches that token from your own endpoint (the JS SDK does this automatically via sessionUrl).
  3. The browser posts events to /api/v1/bugwatch/ingest/browser with the token. On a 401 (expired token) re-fetch and retry once.

Origin allow-list: the project's allowed origins (Dashboard → project → Settings) is enforced on every browser event - a mismatched Origin gets 403 origin_not_allowed. An empty list allows any origin; lock it down before go-live.

Using @newinstance/bugwatch in the browser? Install per Install an SDK → JavaScript & TypeScript, pass sessionUrl (never projectKey), and this wire format is what the SDK produces for you.

POST/api/v1/bugwatch/ingest/browser

Browser ingest – error event

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. Mint a token first and send it as {{sessionToken}}.

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

Headers

x-bugwatch-session

Request body

application/json
{
  "level": 50,
  "time": {{nowMs}},
  "message": "Uncaught TypeError in browser",
  "release": "1.0.0",
  "environment": "production",
  "tags": { "browser": "Chrome", "page": "/checkout" },
  "user": { "id": "usr_browser_001", "ip": "203.0.113.42" },
  "exception": {
    "type": "TypeError",
    "value": "Cannot read properties of null (reading 'getAttribute')",
    "stacktrace": {
      "frames": [
        { "filename": "https://app.example.com/static/js/main.chunk.js", "function": "handleClick", "lineno": 112, "colno": 45 }
      ]
    }
  }
}

Responses

202 – Browser event ingested

{
  "ingested": 1,
  "skipped": 0,
  "deduped": 0
}
boltTry it
env
POSThttps://api.newinstance.cloud/api/v1/bugwatch/ingest/browser

Headers

x-bugwatch-session

Request body

Code samples

curl -X POST 'https://api.newinstance.cloud/api/v1/bugwatch/ingest/browser' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "level": 50,
  "time": {{nowMs}},
  "message": "Uncaught TypeError in browser",
  "release": "1.0.0",
  "environment": "production",
  "tags": { "browser": "Chrome", "page": "/checkout" },
  "user": { "id": "usr_browser_001", "ip": "203.0.113.42" },
  "exception": {
    "type": "TypeError",
    "value": "Cannot read properties of null (reading '\''getAttribute'\'')",
    "stacktrace": {
      "frames": [
        { "filename": "https://app.example.com/static/js/main.chunk.js", "function": "handleClick", "lineno": 112, "colno": 45 }
      ]
    }
  }
}'
arrow_back
Previous
SDK Usage & Event Enrichment
Next
Server Ingest API
arrow_forward