Skip to main content

​
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

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

​
Rate Limits

API requests are rate limited per workspace:
PlanRequests / Minute
Free60
Starter300
Pro1,000
EnterpriseCustom
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.