API Reference

Complete reference for all OneHazel API endpoints.

Base URL

https://api.onehazel.com/

All endpoints are Supabase Edge Functions served from this base URL. Append the function name and path to this URL.

Authentication

All API endpoints require authentication via the Authorization header:

Authorization: Bearer oh_live_YOUR_API_KEY

See Authentication for details on creating and managing API keys.

Response format

All endpoints return JSON responses with a consistent structure:

Success:

{
  "success": true,
  "data": { ... }
}

Error:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Rate limiting

Rate limits are per operator — a single ceiling shared across all of your API keys (issuing more keys does not raise it) — token-bucket with a 60-second window, and are enforced per commercial plan. When exceeded, the API returns HTTP 429 with:

• Retry-After header indicating seconds to wait
• resetAt field in the response body with an ISO 8601 timestamp

Ingest ceilings

Plan	ingest:realtime (per-event writes)	ingest:batch (bulk endpoints)	Effective event throughput
Free trial	250 req/min	30 req/min	~250 events/sec (batch)
Grow	500 req/min	60 req/min	~500 events/sec (batch)
Scale	2,500 req/min	300 req/min	~2,500 events/sec (batch)
Enterprise	10,000 req/min (higher negotiated per contract)	1,200 req/min	10,000 events/sec+ supported

API, gateway & workflow ceilings

Bucket	Free trial	Grow	Scale	Enterprise
api:read	600/min	6,000/min	30,000/min	150,000/min
api:write	300/min	3,000/min	15,000/min	75,000/min
gateway:execute (outbound /gateway/*)	300/min	3,000/min	15,000/min	75,000/min
ingest:read	600/min	3,000/min	15,000/min	75,000/min
workflow:ai	30/min	120/min	600/min	3,000/min

Analytics limits are flat across plans: 200 req/min read, 5 req/min export, 1 req/min refresh.

Headroom. Ceilings are per operator and apply across every key you issue, so adding keys does not increase throughput — move up a plan (Grow → Scale → Enterprise) for a higher ceiling, and prefer the batch endpoints (up to ~6× cheaper per request than realtime writes). For a large one-off backfill, contact us for temporary uplift. If your operator record has no plan set (or during a transient lookup blip) the platform falls back to conservative default ceilings rather than over-throttling. Honour Retry-After; don't stack your own backoff on top.

API groups

Data Ingestion — operator-data-api

Push entities, events, and states into OneHazel.

Method	Endpoint	Description
GET	/operator-data-api/templates	List available data templates
GET	/operator-data-api/settings	Get template and retention config
PUT	/operator-data-api/settings	Set template and retention config
POST	/operator-data-api/entities	Create or update an entity
GET	/operator-data-api/entities/:externalId	Get an entity
DELETE	/operator-data-api/entities/:externalId	Soft-delete entity (GDPR)
POST	/operator-data-api/entities/:externalId/events	Record an event
GET	/operator-data-api/entities/:externalId/events	List entity events
PUT	/operator-data-api/entities/:externalId/state/:key	Update a state snapshot
GET	/operator-data-api/entities/:externalId/state	Get all states
GET	/operator-data-api/entities/:externalId/state/:key	Get a single state
POST	/operator-data-api/batch/entities	Bulk upsert entities (max 1000)
POST	/operator-data-api/batch/events	Bulk insert events (max 5000)
POST	/operator-data-api/batch/states	Bulk upsert states (max 1000)
GET	/operator-data-api/batch/jobs/:jobId	Check batch job status

Gateway — gateway

Proxy requests through to supplier APIs with automatic auth and schema translation.

Method	Endpoint	Description
POST	/gateway	Execute a gateway operation

Webhooks — webhook-receiver

Receive inbound webhooks from external providers.

Method	Endpoint	Description
POST	/webhook-receiver/:connectionId	Receive a webhook

Analytics — analytics-api

Query aggregated analytics data.

Method	Endpoint	Description
GET	/analytics-api/analytics/kpis	Aggregate KPIs
GET	/analytics-api/analytics/revenue	Revenue time series
GET	/analytics-api/analytics/players	Player list
GET	/analytics-api/analytics/players/:id	Player detail
GET	/analytics-api/analytics/games	Game performance
GET	/analytics-api/analytics/providers	Payment provider stats
POST	/analytics-api/analytics/refresh	Refresh materialized views

API Keys — api-keys

Manage your API keys.

Method	Endpoint	Description
POST	/api-keys	Create a new API key
GET	/api-keys	List API keys (masked)
PATCH	/api-keys	Rename a key
DELETE	/api-keys?id=...	Revoke or delete a key

Team Management — onehazel-api

Manage organisation members and invites (the dashboard Team page). See the Team Management guide for the operator walkthrough.

Method	Endpoint	Description
GET	/operators/me/members	List org members
GET	/operators/me/invites	List pending invites
POST	/operators/me/invites	Invite a member
POST	/operators/me/invites/:id/resend	Resend an invite
DELETE	/operators/me/invites/:id	Revoke an invite
PATCH	/operators/me/members/:id	Change role / reinstate
DELETE	/operators/me/members/:id	Revoke (suspend) a member
GET	/invites/lookup?token=...	Validate an invite (public)
POST	/invites/accept	Accept an invite (public)