# 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](/authentication) for details on creating and managing API keys.

## Response format

All endpoints return JSON responses with a consistent structure:

**Success:**

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

**Error:**

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

## Rate limiting

Rate limits are applied per operator. 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

## API groups

### Data Ingestion — `operator-data-api`

Push entities, events, and states into OneHazel.

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

### Gateway — `gateway`

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

| Method | Endpoint | Description |
|---|---|---|
| `POST` | [`/gateway`](/api-reference/gateway) | Execute a gateway operation |

### Webhooks — `webhook-receiver`

Receive inbound webhooks from external providers.

| Method | Endpoint | Description |
|---|---|---|
| `POST` | [`/webhook-receiver/:connectionId`](/api-reference/webhooks) | Receive a webhook |

### Analytics — `analytics-api`

Query aggregated analytics data.

| Method | Endpoint | Description |
|---|---|---|
| `GET` | [`/analytics-api/analytics/kpis`](/api-reference/analytics#kpis) | Aggregate KPIs |
| `GET` | [`/analytics-api/analytics/revenue`](/api-reference/analytics#revenue) | Revenue time series |
| `GET` | [`/analytics-api/analytics/players`](/api-reference/analytics#players) | Player list |
| `GET` | [`/analytics-api/analytics/players/:id`](/api-reference/analytics#player-detail) | Player detail |
| `GET` | [`/analytics-api/analytics/games`](/api-reference/analytics#games) | Game performance |
| `GET` | [`/analytics-api/analytics/providers`](/api-reference/analytics#providers) | Payment provider stats |
| `POST` | [`/analytics-api/analytics/refresh`](/api-reference/analytics#refresh) | Refresh materialized views |

### API Keys — `api-keys`

Manage your API keys.

| Method | Endpoint | Description |
|---|---|---|
| `POST` | [`/api-keys`](/api-reference/api-keys#create) | Create a new API key |
| `GET` | [`/api-keys`](/api-reference/api-keys#list) | List API keys (masked) |
| `PATCH` | [`/api-keys`](/api-reference/api-keys#rename) | Rename a key |
| `DELETE` | [`/api-keys?id=...`](/api-reference/api-keys#revoke) | Revoke or delete a key |