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 SDK sends events with it.

The flow

  1. Your backend calls Server Ingest API → Mint browser session token with the secret DSN key (the JS and PHP SDKs ship ready-made mint helpers; any other backend calls the endpoint directly).
  2. Your page calls initBrowser({ sessionUrl }) pointing at your own mint endpoint (never projectKey) - see Install an SDK → JavaScript & TypeScript.
  3. The SDK captures errors, batches events and posts them with x-bugwatch-session, re-fetching the token before expiry and on a 401 automatically.

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

The browser wire contract accepts the same event shape as Server Ingest API (including breadcrumbs[], contexts{} and causes[]), authenticated with x-bugwatch-session instead of the key; the SDK produces it for you. Browser sessionUrl mode captures errors and logs only; span creation needs a server-side projectKey (the JS wrapFetch still injects traceparent in the browser so your backend joins the page's trace).

POST/api/v1/bugwatch/ingest/browser

Browser ingest - error event (session token)

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.

Headers

x-bugwatch-session

Request body

application/json
{
  "level": 50,
  "time": {{nowMs}},
  "message": "Uncaught TypeError: Cannot read properties of undefined",
  "release": "web@3.1.0",
  "eventId": "evt_browser_abc123",
  "tags": { "surface": "spa", "route": "/checkout" },
  "user": { "id": "usr_456" },
  "contexts": { "cart": { "id": "cart_42", "items": 3 } },
  "breadcrumbs": [
    { "timestamp": {{nowMs}}, "category": "navigation", "message": "Navigated to /checkout", "level": 30 }
  ],
  "exception": {
    "type": "TypeError",
    "value": "Cannot read properties of undefined",
    "stacktrace": { "frames": [ { "filename": "checkout.js", "function": "calculateTotal", "lineno": 42, "colno": 15 } ] }
  }
}

Responses

202 – Accepted

{
  "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: Cannot read properties of undefined",
  "release": "web@3.1.0",
  "eventId": "evt_browser_abc123",
  "tags": { "surface": "spa", "route": "/checkout" },
  "user": { "id": "usr_456" },
  "contexts": { "cart": { "id": "cart_42", "items": 3 } },
  "breadcrumbs": [
    { "timestamp": {{nowMs}}, "category": "navigation", "message": "Navigated to /checkout", "level": 30 }
  ],
  "exception": {
    "type": "TypeError",
    "value": "Cannot read properties of undefined",
    "stacktrace": { "frames": [ { "filename": "checkout.js", "function": "calculateTotal", "lineno": 42, "colno": 15 } ] }
  }
}'
arrow_back
Previous
SDK Usage & Event Enrichment
Next
Server Ingest API
arrow_forward