API reference

One header. One JSON envelope.

Most developers never call this directly — the SDK does it for you. But the whole contract is small, so here it is, hand-authored and complete.

On this page

Base URL & auth
Endpoints
Notice envelope
Sensitive-value filtering
Responses
Verify with curl
Release tracking

Base URL & auth

Base URL & authentication

All requests are POST to your project's ingest endpoint. Authenticate every request with a single project-key header.

http

POST https://<your-endpoint>/api/projects/{project_slug}/notices
x-errorgap-project-key: <key>
content-type: application/json
user-agent: errorgap-{lang}/{version}

The only header the API reads is x-errorgap-project-key. Note that X-Errorgap-Api-Key is not accepted. Set a descriptive User-Agent so requests are attributable in logs.

Endpoints

Purpose	Method	Path
Errors	POST	/api/projects/{project_slug}/notices
APM transactions	POST	/api/projects/{project_slug}/transactions
Session replay	POST	/api/projects/{project_slug}/sessions
Release tracking optional	POST	/api/projects/{project_slug}/releases

Notice envelope

The body sent to /notices. One envelope can carry multiple errors (e.g. an error chain).

json

{
  "received_at": "2026-06-23T10:14:05Z",
  "errors": [
    {
      "type": "TypeError",
      "message": "Cannot read properties of undefined (reading 'id')",
      "backtrace": [
        { "file": "app/checkout.js", "line": 42, "function": "applyCoupon", "in_app": true }
      ]
    }
  ],
  "context": {
    "notifier": "errorgap-node",
    "notifier_version": "0.1.0",
    "release": "a1b2c3d",
    "environment": "production"
  },
  "params": { "coupon": "[FILTERED]" }
}

Required

received_at — ISO-8601 timestamp
errors[] — each with type + message
context.notifier
context.notifier_version

Optional

project_id
backtrace[].in_app
context.release · context.root_directory
environment · session · params

Sensitive values

Sensitive-value filtering

SDKs mask sensitive values before they leave the host. The default key list is matched as a case-insensitive substring; any match has its value replaced with "[FILTERED]". Filtering applies to params only.

default mask list

password   token   secret   api_key   authorization   cookie
# substring match, case-insensitive — "x_api_key" also matches "api_key"

Responses

Code	Meaning	Body
201	Accepted	JSON with group_id
202	Accepted, sampled	Accepted but rate-limited or sampled
401	Unauthorized	Bad or missing project key

Release tracking additionally returns 200 (release already recorded) and 403 (key lacks release scope).

Verify

Verify with curl

Send a test error with nothing but curl. A 201 with a group_id means ingestion works.

bash

curl -X POST https://<your-endpoint>/api/projects/$SLUG/notices \
  -H "x-errorgap-project-key: $KEY" \
  -H "content-type: application/json" \
  -d '{"received_at":"2026-06-23T10:14:05Z",
       "errors":[{"type":"TestError","message":"hello from curl"}],
       "context":{"notifier":"curl","notifier_version":"0"}}'

Release tracking

Release tracking optional

Post a release so errors can be attributed to the deploy that introduced them.

json

{
  "version": "a1b2c3d",
  "environment": "production",
  "deployed_at": "2026-06-23T10:00:00Z"
}

Code	Meaning
201	Release recorded
200	Release already existed
403	Key lacks release scope