> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getimmutable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for the Immutable REST API.

## Base URL

```
https://getimmutable.dev/api/v1
```

All endpoints are prefixed with `/api/v1`.

## Authentication

Include your API key as a Bearer token in the `Authorization` header:

```
Authorization: Bearer imk_your_api_key_here
```

See [Authentication](/authentication) for details on key management, IP allowlisting, and rate limits.

## Request Format

* All request bodies must be JSON with `Content-Type: application/json`.
* All timestamps use ISO 8601 format with optional microsecond precision.

## Response Format

Successful responses return JSON. Event ingestion endpoints return `202 Accepted` to indicate asynchronous processing.

## Error Format

Error responses use a consistent structure:

```json theme={null}
{
  "error": "validation_failed",
  "message": "The actor_id field is required."
}
```

### Status Codes

| Status | Meaning                                                                 |
| ------ | ----------------------------------------------------------------------- |
| `200`  | Success.                                                                |
| `202`  | Accepted -- event is queued for async processing.                       |
| `302`  | Redirect -- follow the `Location` header (used for export downloads).   |
| `400`  | Bad request -- malformed JSON or invalid parameters.                    |
| `401`  | Unauthenticated -- missing or invalid API key.                          |
| `403`  | Forbidden -- IP not in allowlist or insufficient permissions.           |
| `404`  | Not found -- resource does not exist.                                   |
| `409`  | Conflict -- resource not in expected state (e.g. export not completed). |
| `410`  | Gone -- resource has expired (e.g. export download link).               |
| `422`  | Validation failed -- check the `message` field.                         |
| `429`  | Rate limited -- retry after the `Retry-After` header value.             |
| `500`  | Server error -- contact support.                                        |

## Rate Limits

API requests are rate limited per workspace:

| Plan       | Requests / Minute |
| ---------- | ----------------- |
| Free       | 60                |
| Starter    | 300               |
| Pro        | 1,000             |
| Enterprise | Custom            |

When rate limited, the response includes a `Retry-After` header.

## Cursor Pagination

List endpoints use cursor-based pagination with URL-safe base64 cursors encoding microsecond-precision timestamps.

### Response Shape

```json theme={null}
{
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMy0xNVQxNDozMjoxOC44NDczMTJaIn0",
    "total": 4821
  }
}
```

<ResponseField name="data" type="array">
  Array of results for the current page.
</ResponseField>

<ResponseField name="pagination.has_more" type="boolean">
  Whether more results exist beyond this page.
</ResponseField>

<ResponseField name="pagination.next_cursor" type="string | null">
  URL-safe base64 cursor to pass as the `cursor` query parameter for the next page. Only present when `has_more` is `true`.
</ResponseField>

<ResponseField name="pagination.total" type="integer">
  Total number of results matching the query.
</ResponseField>

### Usage

```bash theme={null}
# First page
GET /api/v1/events?limit=25

# Next page
GET /api/v1/events?limit=25&cursor=eyJjcmVhdGVkX2F0Ijoi...
```

## Async Responses

Event ingestion endpoints (`POST /api/v1/events` and `POST /api/v1/events/batch`) return `202 Accepted`. The event ID is pre-generated and returned immediately while processing (hash computation, geo enrichment, alert evaluation, log stream fanout) happens asynchronously.