Getting started

REST API

Recalled ships as a plain HTTPS + JSON API. Any language with an HTTP client can send events, not just Node. The npm SDK is a thin wrapper over these same endpoints.

Base URL

text

https://api.recalled.dev/v1

Required headers

Every request to /v1/* carries:

text

Authorization: Bearer rec_live_<prefix>_<secret>
Content-Type: application/json

Content-Type is only required on requests that have a body (POST, PUT, PATCH). See Authentication for the key format and scopes.

Response envelope

Single-resource responses are wrapped in data:

json

{
  "data": { "id": "evt_01HX...", "action": "invoice.deleted" }
}

List responses add a cursor:

json

{
  "data": [{ "id": "evt_01HX..." }],
  "nextCursor": "2026-04-14T09:12:45.000Z"
}

Errors are always:

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "action is required",
    "details": {}
  }
}

Full error catalog: Error codes.

Endpoints

Method	Path	What it does
`POST`	`/v1/events`	Ingest a new event
`GET`	`/v1/events`	List events, cursor pagination + filters
`GET`	`/v1/events/search`	Full-text search
`GET`	`/v1/events/:id`	Read one event
`GET`	`/v1/events/verify`	Verify hash chain and signatures
`GET`	`/v1/exports`	Download CSV or JSON export
`DELETE`	`/v1/actors/:id`	GDPR erasure for one actor
`POST`	`/v1/embed/token`	Mint a short-lived embed token

Each endpoint is documented in detail in Events API, GDPR and Embeddable UI.

Try it from your terminal

bash

curl -X POST https://api.recalled.dev/v1/events \
  -H "Authorization: Bearer $RECALLED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "user.login",
    "actor": { "id": "user_123" },
    "organization": "org_acme"
  }'

Pagination

List and search endpoints use cursor pagination keyed on occurred_at. The response contains nextCursor; pass it back on the next call until it returns null.

bash

curl "https://api.recalled.dev/v1/events?limit=50&cursor=2026-04-14T09:12:45.000Z" \
  -H "Authorization: Bearer $RECALLED_API_KEY"

Rate limits

POST /v1/events: 1200 requests per minute per API key
Other endpoints: 1500 requests per minute per IP

Every response carries IETF RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. See Rate limits.

Use from any language, runnable snippets in Python, Go, PHP, Ruby, Java, Rust and more
Authentication, key format, scopes, embed tokens
Events API, every field and query param documented

REST API

Base URL

Required headers

Response envelope

Endpoints

Try it from your terminal

Pagination

Rate limits

Next