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

# Ingest Event

> Record a single audit log event.

## POST /api/v1/events

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

### Request Body

<ParamField body="actor_id" type="string" required>
  Identifier of the actor who performed the action.
</ParamField>

<ParamField body="actor_name" type="string">
  Human-readable name of the actor.
</ParamField>

<ParamField body="actor_type" type="string">
  Type of actor (e.g. `user`, `system`, `api_client`).
</ParamField>

<ParamField body="action" type="string" required>
  The action performed, typically in `resource.verb` format.
</ParamField>

<ParamField body="action_category" type="string">
  Category for grouping actions (e.g. `documents`, `billing`).
</ParamField>

<ParamField body="resource_id" type="string">
  Identifier of the primary resource affected.
</ParamField>

<ParamField body="resource_name" type="string">
  Human-readable name of the resource.
</ParamField>

<ParamField body="resource" type="string">
  Resource type (e.g. `document`, `invoice`).
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary JSON object for additional context.
</ParamField>

<ParamField body="targets" type="array">
  Array of target objects. Each target has `type` (required), `id`, `name`, and optional `metadata`.
</ParamField>

<ParamField body="occurred_at" type="string">
  ISO 8601 timestamp of when the event occurred. Defaults to server time.
</ParamField>

<ParamField body="session_id" type="string">
  Session identifier for grouping related events.
</ParamField>

<ParamField body="tenant_id" type="string">
  Tenant identifier for multi-tenant isolation.
</ParamField>

<ParamField body="idempotency_key" type="string">
  Unique key for deduplication. If a duplicate is detected, returns the original event ID with status `duplicate`.
</ParamField>

<ParamField body="version" type="integer">
  Schema version number for the event.
</ParamField>

### Response

Returns `202 Accepted`:

```json theme={null}
{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "queued"
}
```

If a duplicate `idempotency_key` is detected:

```json theme={null}
{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "duplicate"
}
```

### Examples

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```typescript JavaScript theme={null}
  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",
  });
  ```

  ```php Laravel theme={null}
  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'],
      ]);
  ```
</CodeGroup>