Ingest Event

POST /api/v1/events

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

Request Body

string

required

Identifier of the actor who performed the action.

string

Human-readable name of the actor.

string

Type of actor (e.g. user, system, api_client).

string

required

The action performed, typically in resource.verb format.

string

Category for grouping actions (e.g. documents, billing).

string

Identifier of the primary resource affected.

string

Human-readable name of the resource.

string

Resource type (e.g. document, invoice).

object

Arbitrary JSON object for additional context.

array

Array of target objects. Each target has type (required), id, name, and optional metadata.

string

ISO 8601 timestamp of when the event occurred. Defaults to server time.

string

Session identifier for grouping related events.

string

Tenant identifier for multi-tenant isolation.

string

Unique key for deduplication. If a duplicate is detected, returns the original event ID with status duplicate.

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"
  }'

import { ImmutableClient } from "getimmutable";

const client = new ImmutableClient({
  apiKey: "imk_your_api_key_here",
  baseUrl: "https://getimmutable.dev",
});

const result = await client.track({
  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",
});

use GetImmutable\AuditLog;

AuditLog::actor(['id' => 'user_2hG9kLm', 'name' => 'Sarah Chen'])
    ->session('sess_4kN8pLm')
    ->actionCategory('documents')
    ->target('folder', 'folder_3mK9pLq', 'Shared Reports')
    ->track('document.created', 'document', [
        'resource_id' => 'doc_8nXpQr3',
        'resource_name' => 'Q4 Financial Report',
        'tenant_id' => 'org_7rT2xBc',
        'metadata' => ['folder' => 'reports', 'template' => 'quarterly'],
    ]);

Overview

Events

Verification

Exports

Anchors

Other

POST /api/v1/events

Request Body

Response

Examples

​POST /api/v1/events

​Request Body

​Response

​Examples

POST /api/v1/events

Request Body

Response

Examples