Observability protocol

This is the wire format the observability module ingests. It is deliberately small and fully documented so that a language without a first-party SDK is a copy-paste away rather than a support ticket.

The canonical definition lives in packages/core/src/observe/envelope.ts. This page describes exactly that schema.

# Endpoint

POST /api/ingest/v1/<publicKey>
Content-Type: application/json

publicKey is the ink_pub_… credential from your project’s DSN. It is public by design.

• CORS is open (Access-Control-Allow-Origin: *); OPTIONS is handled.
• Send no credentials — the endpoint ignores cookies, and sending them breaks the wildcard CORS response.
• Success is 202 Accepted with { "accepted": n, "dropped": n }.

# Response codes

# The envelope

{
  "sdk": { "name": "inline-observe.javascript", "version": "0.1.0" },
  "sentAt": "2026-08-15T10:32:00.000Z",
  "environment": "production",
  "release": "1.4.0",
  "releaseCommit": "9f2c1ab…",
  "platform": "javascript",
  "events": [ /* 1–100 events */ ]
}

Only events is required. environment, release, releaseCommit and platform at the envelope level are defaults applied to any event that omits them — so a batching client sends them once.

Three shorthand forms are accepted, for the smallest possible integration:

{ "events": [ { … } ] }   // canonical
[ { … }, { … } ]          // a bare array of events
{ "message": "boom" }     // a single bare event

# snake_case is accepted

Every key is normalized, so event_id, release_commit, in_app and context_line parse identically to their camelCase spellings. line_no and line normalize to lineno; col_no and column to colno; abs_path to filename. Write idiomatic Python or Go without a translation layer.

The keys inside tags, extra, contexts, data and headers are your data, not protocol, and are preserved verbatim.

# An event

# exception

{
  "exception": {
    "values": [{
      "type": "TypeError",
      "value": "Cannot read properties of undefined (reading 'id')",
      "mechanism": { "type": "onunhandledrejection", "handled": false },
      "stacktrace": { "frames": [ /* … */ ] }
    }]
  }
}

values is an array so chained/caused-by exceptions have somewhere to live; the first entry is the one that groups and titles the issue.

# Frames — newest first

This is the one place inline differs from what you may expect. Sentry orders frames oldest-first, with the crash at the bottom. inline orders them newest first: frames[0] is where the error was thrown. Every reader — human or model — wants the crash site first, and it’s also the order every JS engine already produces.

Server runtimes can usually fill in the context lines directly; for minified browser code inline recovers them from your uploaded source maps.

# Breadcrumbs

{
  "timestamp": "2026-08-15T10:31:58.220Z",
  "type": "http",
  "category": "fetch",
  "level": "warning",
  "message": "POST /api/checkout → 500",
  "data": { "status": 500, "durationMs": 812 }
}

Ordered oldest → newest, ending at the error. In practice this is the fastest route to a reproduction — the culprit is more often the failed request two rows up than the frame that happened to throw.

# Limits

# Source-map upload

POST /api/observe/artifacts?release=<version>&name=<url-path>&commitSha=<sha>&environment=<env>
Authorization: Bearer <write key>
Content-Type: application/json

<the raw .map file as the body>

Metadata in the query string, raw bytes as the body — so curl --data-binary @file works and no multipart parsing is needed anywhere.

name is the URL path of the bundle (not the map), by convention prefixed with ~: ~/_next/static/chunks/page-ab12.js. inline reduces it to a match key the same way it reduces incoming stack-frame URLs, which is how the two meet.

# Worked example

{
  "sdk": { "name": "python-manual", "version": "1.0.0" },
  "environment": "production",
  "release": "2026.08.15",
  "release_commit": "9f2c1ab7d4e",
  "events": [{
    "level": "error",
    "platform": "python",
    "transaction": "POST /api/claims",
    "exception": {
      "values": [{
        "type": "KeyError",
        "value": "'member_id'",
        "stacktrace": {
          "frames": [
            { "filename": "app/claims.py", "function": "submit", "line_no": 88, "in_app": true },
            { "filename": "app/routes.py", "function": "handle", "line_no": 42, "in_app": true },
            { "filename": "site-packages/flask/app.py", "function": "dispatch", "line_no": 1502, "in_app": false }
          ]
        }
      }]
    },
    "breadcrumbs": [
      { "category": "db", "message": "SELECT member WHERE id=… → 0 rows", "level": "warning" }
    ],
    "tags": { "tenant": "acme" },
    "user": { "id": "u_8123" }
  }]
}

Reported this way, the issue groups on KeyError + submit/handle, shows the breadcrumb that explains it, counts one affected user — and if the project is linked to a repo, the root-cause agent opens app/claims.py at commit 9f2c1ab7d4e and reads line 88.