REST API reference

Base URL#

All requests go to the base URL for your workspace's region. Requests to the wrong region return 421 Misdirected Request with the correct URL in the response.

Authentication#

Create a secret key under Settings → API keys. Keys start with sk_live_, belong to one workspace and can be limited to read-only access. Send the key as a bearer token on every request:

curl https://api.aurora.io/v1/visitors \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY" 

Keep secret keys on your server. Never embed them in browser code, mobile apps or public repositories — the tracker uses the separate public key (pk_live_) for that. A leaked key can be revoked instantly from the same settings page; revoked keys stop working within seconds.

Versioning#

Breaking changes are released as dated versions. Pin a version with the Aurora-Version header; without it, requests use the version that was current when the key was created. The current version is 2026-08-01. Additive changes — new endpoints, new optional parameters, new fields in responses — are made without a new version, so your client should ignore fields it doesn't recognize.

Pagination#

List endpoints return up to 25 objects by default and up to 100 with the limit parameter. Pass the next_cursor value from a response as cursor to fetch the next page, and stop when has_more is false.

{
  "object": "list",
  "data": [
    {
      "id": "vis_7c1e02",
      "email": "dana@northwind.example",
      "score": 94,
      "status": "ready",
      "last_seen_at": "2026-08-24T09:41:12Z"
    }
  ],
  "has_more": true,
  "next_cursor": "vis_7c1e02"
}

Errors#

Aurora uses conventional HTTP status codes: 2xx for success, 4xx for problems with the request and 5xx for problems on our side. Every error response has the same JSON shape, including a request_id to quote when contacting support.

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "min_score must be an integer between 0 and 100.",
    "param": "min_score",
    "request_id": "req_2Lq8fX0a"
  }
}

Idempotency#

To retry POST requests safely, send a unique Idempotency-Key header (a UUID works well). If the same key is sent again within 24 hours, Aurora returns the original response instead of performing the action twice.

Rate limits#

Each key can make 600 requests per minute. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. When you exceed the limit, the API returns 429 with a Retry-After header in seconds — back off and retry rather than polling faster. For bulk jobs, use list endpoints with limit=100 and webhooks for real-time changes instead of polling individual visitors.

Visitors#

List visitors#

Returns visitors sorted by last_seen_at, newest first.

Retrieve a visitor#

Returns the full visitor profile, including traits, account, top signals and the 50 most recent sessions. Add ?expand=events to include every event.

Identify a visitor#

Links an anonymous visitor to a user server-side. Send visitor_id (the aur_vid value), user_id and traits, with the same rules as the browser method.

Delete a visitor#

Permanently deletes the visitor, their events and scores. Use it to fulfil erasure requests. Returns 204.

Scores#

Query scores#

Returns score history for one or more visitors, useful for reporting in your own warehouse. Filter with visitor_id, from and to; each entry includes the score, the rule that changed it and the timestamp.

Rules#

List rules#

Returns scoring rules, including drafts when ?include_drafts=true.

Create a rule#

curl https://api.aurora.io/v1/rules \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d0e6c5a-1f7b-4b8e-9d0a-5c2f6a1e3b44" \
  -d '{
    "name": "Pricing page",
    "signal": { "type": "page_viewed", "match": "starts_with", "value": "/pricing" },
    "weight": 24,
    "frequency": "once_per_session",
    "status": "draft"
  }'

Update a rule#

Updates any field. Set "status": "published" to publish a draft, and "rescore": true to re-score recent visitors.

Webhooks#

Create an endpoint#

Registers a webhook endpoint. Send url and an array of events. The response includes the signing secret, which is only returned once. See Webhooks for payloads and verification.

List endpoints#

Delete an endpoint#

Stops deliveries immediately. Events already queued for the endpoint are discarded.

Team#

List team members#

Returns team members with their role, status (active, away, deactivated), territories and routing groups. Useful for keeping routing in sync with your HR or scheduling system.

SDKs and tools#

Official client libraries are available for Node.js (@aurora-io/node) and Python (aurora-io). They handle authentication, pagination, retries with backoff and webhook signature verification. An OpenAPI 3.1 specification is published at https://api.aurora.io/v1/openapi.json for generating clients in other languages or importing into Postman.