Observe API

The Observe API receives error events from the Statly SDKs. This endpoint is used internally by the SDKs but can be called directly for custom integrations.

Event Ingestion

POST /api/v1/observe/ingest

Send error events to Statly for tracking and analysis.

Authentication

Use either:

DSN Header: X-Statly-DSN: https://[email protected]/your-org
Bearer Token: Authorization: Bearer sk_live_xxx

Request Body

Single event:

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-01-15T12:00:00Z",
  "level": "error",
  "message": "Cannot read property 'x' of undefined",
  "platform": "javascript",
  "sdk": {
    "name": "@statly/observe",
    "version": "0.1.0"
  },
  "exception": {
    "type": "TypeError",
    "value": "Cannot read property 'x' of undefined",
    "stacktrace": {
      "frames": [
        {
          "filename": "app.js",
          "function": "handleClick",
          "lineno": 42,
          "colno": 12
        }
      ]
    }
  },
  "environment": "production",
  "release": "1.2.3",
  "user": {
    "id": "user_123",
    "email": "[email protected]"
  },
  "tags": {
    "browser": "Chrome",
    "page": "/dashboard"
  },
  "breadcrumbs": [
    {
      "timestamp": "2024-01-15T11:59:50Z",
      "category": "navigation",
      "message": "Navigated to /dashboard",
      "level": "info"
    }
  ]
}

Batch events:

{
  "events": [
    { /* event 1 */ },
    { /* event 2 */ }
  ]
}

Event Fields

Field	Type	Required	Description
`message`	string	Yes	Error message
`level`	string	No	debug, info, warning, error, fatal
`timestamp`	string	No	ISO 8601 timestamp
`platform`	string	No	javascript, python, go
`exception`	object	No	Exception details with stack trace
`environment`	string	No	production, staging, development
`release`	string	No	Application version
`user`	object	No	User context
`tags`	object	No	Key-value tags
`extra`	object	No	Additional context data
`breadcrumbs`	array	No	Trail of events before error

Response

{
  "id": "evt_abc123",
  "status": "accepted"
}

Example: Direct Ingestion

curl -X POST "https://statly.live/api/v1/observe/ingest" \
  -H "X-Statly-DSN: https://[email protected]/your-org" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Test error",
    "level": "error",
    "environment": "production"
  }'

Source Maps

POST /api/v1/observe/sourcemaps

Upload source maps for stack trace deobfuscation.

Request

Multipart form data:

file: Source map file (.map)
release: Release version
name: Original filename

curl -X POST "https://statly.live/api/v1/observe/sourcemaps" \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "[email protected]" \
  -F "release=1.2.3" \
  -F "name=app.js"

Response

{
  "id": "sm_abc123",
  "filename": "app.js",
  "release": "1.2.3",
  "size": 125000
}

Error Processing

When events are ingested:

Fingerprinting: Similar errors are grouped by stack trace
Issue Creation: New fingerprints create issues in your dashboard
Rate Calculation: Error rates are computed per release
Alerting: Spike detection triggers notifications

DSN Format

The Data Source Name (DSN) encodes your API key and organization:

https://<api-key>@statly.live/<org-slug>

Example:

https://[email protected]/acme

The SDK parses this to construct the ingest URL and authentication headers.

Rate Limits

The observe endpoint has separate rate limits:

Plan	Events per Minute
Free	100
Hobby	1,000
Pro	10,000
Enterprise	Unlimited

Excess events are sampled (not rejected) to prevent data loss.

Status Error Codes