Public API

Read customers and analytics, and record events, with scoped API keys.

The REST API lives under /api/v1. All requests and responses are JSON.

Authentication

Create a key in Developers. A key is shown once, so store it safely. Send it as a Bearer token:

curl https://YOUR-APP/api/v1/customers \
  -H "Authorization: Bearer orb_YOUR_KEY"

Keys are either read only or read and write. Only the SHA-256 hash of a key is stored. Revoking a key stops it working immediately.

Endpoints

Method and path	Needs	What it does
`GET /api/v1/me`	read	The workspace, plan and scope the key belongs to
`GET /api/v1/customers`	read	List customers with search, filters and paging
`POST /api/v1/customers`	write	Create a customer
`GET /api/v1/customers/:id`	read	One customer
`DELETE /api/v1/customers/:id`	write	Delete a customer
`GET /api/v1/analytics`	read	The analytics report for a date range
`POST /api/v1/events`	write	Record an event from your server

List customers

Query parameters:

Parameter	Meaning
`q`	Search name, email and company
`status`	`Active`, `Trial` or `Churned`
`plan`	`Starter`, `Growth` or `Scale`
`sort`	`name`, `email`, `plan`, `status`, `mrr` or `joined`
`dir`	`asc` or `desc`
`page`, `pageSize`	Paging. `pageSize` is 1 to 50, default 10

{
  "data": [
    { "id": "…", "name": "Maya Chen", "email": "maya@lumen.io", "company": "Lumen",
      "plan": "Scale", "status": "Active", "mrr": 199, "joined": "2026-01-14" }
  ],
  "total": 12, "page": 1, "pages": 2
}

Create a customer

curl -X POST https://YOUR-APP/api/v1/customers \
  -H "Authorization: Bearer orb_YOUR_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Grace Hopper", "email": "grace@navy.mil", "plan": "Growth", "mrr": 49 }'

Only name and email are required. Emails are unique within a workspace.

Analytics

GET /api/v1/analytics?range=30d accepts 7d, 30d or 90d, or from and to dates (YYYY-MM-DD, up to 366 days). The response contains totals with the change against the previous period, a daily series, traffic sources and top pages.

Record an event

curl -X POST https://YOUR-APP/api/v1/events \
  -H "Authorization: Bearer orb_YOUR_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "purchase", "value": 99, "visitor": "user_123" }'

Errors

Errors return { "error": "message" } and a standard status code.

Status	Meaning
400	The body is not valid JSON
401	The key is missing, malformed, unknown or revoked
402	A plan limit was reached, such as the monthly event allowance
403	A read-only key was used for a write
404	The record does not exist in your workspace
409	A duplicate, such as an email that already exists
422	Validation failed. A `fields` object names the problems
429	Rate limit reached. Retry after the `Retry-After` header

Limits

Each key may make 600 requests per 15 minutes. Keys only ever see their own workspace.