API Reference

Beacon provides a REST API for direct integration when an SDK is not suitable for your environment. The API is used internally by all Beacon SDKs.

Interactive Documentation

Full interactive API documentation is available at:

Beacon API Reference (Scalar)

The API documentation URL will be available when Beacon launches. The interactive docs let you explore endpoints, view request/response schemas, and test calls directly from your browser.

Authentication

All ingestion API requests require an API key passed as a Bearer token in the Authorization header:

curl -X POST https://api.beacon.softagility.com/v1/events \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '[{
    "event_id": "01912345-6789-7abc-def0-123456789abc",
    "category": "reports",
    "name": "report_exported",
    "timestamp": "2026-03-20T14:30:00Z",
    "actor_id": "user-123",
    "source_app": "MyApp",
    "source_version": "1.2.0",
    "properties": { "format": "pdf", "row_count": "1500" }
  }]'

Base URL

https://api.beacon.softagility.com/v1

Ingestion Endpoints

MethodEndpointDescription
POST/v1/eventsTrack one or more events (batch, up to 1000)
POST/v1/events/sessionsStart a new session
POST/v1/events/sessions/endEnd an active session
POST/v1/events/exceptionsReport an exception with stack trace

POST /v1/events

Send a JSON array of event objects. Max payload 1 MB, max 1000 events per batch.

Required fields per event:

  • event_id — UUID (v7 recommended)
  • category — String, max 128 chars
  • name — String, max 256 chars
  • timestamp — ISO 8601 datetime
  • actor_id — String, max 512 chars

Optional fields:

  • source_app — Application name
  • source_version — Application version
  • properties — Object with custom properties
  • session_id — UUID linking event to a session

Response: 200 (all accepted), 207 (partial success), 400 (validation error), 401 (invalid API key), 402 (plan event limit reached), 413 (payload too large), 429 (rate limited)

POST /v1/events/sessions

Start a new session.

Required fields: session_id, actor_id, source_app, source_version, started_at

POST /v1/events/sessions/end

End an active session.

Required fields: session_id, ended_at, end_reason

POST /v1/events/exceptions

Report an exception.

Required fields: exception_id, exception_type, severity (fatal or non_fatal), occurred_at, actor_id, source_app, source_version

Optional fields: message (max 1000 chars), stack_trace (max 32,768 chars), breadcrumbs (JSON array), session_id, environment_context

Response: 200 with { "exception_id": "...", "status": "accepted", "fingerprint": "..." }

Rate Limits

Rate limits are per-minute and configurable per plan. Rate limit headers are included in every response:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 1711929600

When rate limited, the API returns 429 with a Retry-After header.

Hard Caps

When a tenant reaches their plan's monthly event limit, the API returns 402 Payment Required. Events are rejected until the limit resets or the plan is upgraded. SDKs queue events locally during hard cap periods and retry automatically.

SDKs

For most integrations, we recommend using an SDK instead of the API directly. SDKs handle batching, offline persistence, session management, breadcrumbs, and retry logic automatically.

JavaScript / TypeScript SDK

All Documentation