API Reference

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 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:

{
  "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

{
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMy0xNVQxNDozMjoxOC44NDczMTJaIn0",
    "total": 4821
  }
}

data

array

Array of results for the current page.

pagination.has_more

boolean

Whether more results exist beyond this page.

pagination.next_cursor

string | null

URL-safe base64 cursor to pass as the cursor query parameter for the next page. Only present when has_more is true.

pagination.total

integer

Total number of results matching the query.

Usage

# 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.

Overview

Events

Verification

Exports

Anchors

Other

Base URL

Authentication

Request Format

Response Format

Error Format

Status Codes

Rate Limits

Response Shape

Usage

Async Responses

​Base URL

​Authentication

​Request Format

​Response Format

​Error Format

​Status Codes

​Rate Limits

​Cursor Pagination

​Response Shape

​Usage

​Async Responses

Base URL

Authentication

Request Format

Response Format

Error Format

Status Codes

Rate Limits

Cursor Pagination

Response Shape

Usage

Async Responses