Skip to main content

​
POST /api/v1/events

Ingest a single event into your workspace audit log. Returns 202 Accepted with a pre-generated UUID.

​
Request Body

​
actor_id
string
required
Identifier of the actor who performed the action.
​
actor_name
string
Human-readable name of the actor.
​
actor_type
string
Type of actor (e.g. user, system, api_client).
​
action
string
required
The action performed, typically in resource.verb format.
​
action_category
string
Category for grouping actions (e.g. documents, billing).
​
resource_id
string
Identifier of the primary resource affected.
​
resource_name
string
Human-readable name of the resource.
​
resource
string
Resource type (e.g. document, invoice).
​
metadata
object
Arbitrary JSON object for additional context.
​
targets
array
Array of target objects. Each target has type (required), id, name, and optional metadata.
​
occurred_at
string
ISO 8601 timestamp of when the event occurred. Defaults to server time.
​
session_id
string
Session identifier for grouping related events.
​
tenant_id
string
Tenant identifier for multi-tenant isolation.
​
idempotency_key
string
Unique key for deduplication. If a duplicate is detected, returns the original event ID with status duplicate.
​
version
integer
Schema version number for the event.

​
Response

Returns 202 Accepted: 
{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "queued"
}
If a duplicate idempotency_key is detected: 
{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "duplicate"
}

​
Examples

curl -X POST https://getimmutable.dev/api/v1/events \
  -H "Authorization: Bearer imk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "actor_id": "user_2hG9kLm",
    "actor_name": "Sarah Chen",
    "actor_type": "user",
    "action": "document.created",
    "action_category": "documents",
    "resource_id": "doc_8nXpQr3",
    "resource_name": "Q4 Financial Report",
    "resource": "document",
    "metadata": {
      "folder": "reports",
      "template": "quarterly"
    },
    "targets": [
      { "type": "folder", "id": "folder_3mK9pLq", "name": "Shared Reports" }
    ],
    "session_id": "sess_4kN8pLm",
    "tenant_id": "org_7rT2xBc"
  }'