> ## Documentation Index
> Fetch the complete documentation index at: https://docs.provenlog.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingest Events

> Send events to the audit trail

## POST /v1/events

Ingest a single event.

### Request body

```json theme={null}
{
  "agent_id": "my-agent",
  "action_type": "TOOL_CALL",
  "action_name": "search_database",
  "action_input": {"query": "revenue Q4"},
  "action_output": {"results": 42},
  "action_status": "success",
  "timestamp": "2026-02-17T10:30:00Z",
  "duration_ms": 150,
  "labels": {"env": "prod"},
  "metadata": {"model": "claude-sonnet-4-5-20250929"}
}
```

### Required fields

| Field      | Type   | Description                                     |
| ---------- | ------ | ----------------------------------------------- |
| `agent_id` | string | Agent identifier (partition key for hash chain) |

All other fields are optional. See [Event Schema](/concepts/events) for the complete field reference.

### Response

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "schema_version": "1.0",
  "agent_id": "my-agent",
  "action_type": "TOOL_CALL",
  "action_name": "search_database",
  "sequence": 42,
  "hash": "sha256...",
  "prev_hash": "sha256...",
  "..."
}
```

### Example

```bash theme={null}
curl -X POST http://localhost:7600/v1/events \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-agent",
    "action_type": "TOOL_CALL",
    "action_name": "search_database",
    "action_status": "success"
  }'
```

***

## POST /v1/batch

Ingest multiple events in a single request.

### Request body

Array of events:

```json theme={null}
[
  {
    "agent_id": "my-agent",
    "action_type": "TOOL_CALL",
    "action_name": "search",
    "action_status": "success"
  },
  {
    "agent_id": "my-agent",
    "action_type": "TOOL_RESULT",
    "action_name": "search",
    "action_status": "success",
    "action_output": {"results": 42}
  }
]
```

### Response

Returns `207 Multi-Status` on partial failure, or `201 Created` on full success. The response is an array of per-event results:

```json theme={null}
[
  {"index": 0, "event": {"id": "...", "sequence": 42, "...": "..."}},
  {"index": 1, "event": {"id": "...", "sequence": 43, "...": "..."}}
]
```

On error for a specific event:

```json theme={null}
[
  {"index": 0, "event": {"id": "...", "sequence": 42, "...": "..."}},
  {"index": 1, "error": "agent_id is required"}
]
```

This lets the client know exactly which events succeeded — no silent data loss.

### Example

```bash theme={null}
curl -X POST http://localhost:7600/v1/batch \
  -H "Content-Type: application/json" \
  -d '[
    {"agent_id": "a1", "action_type": "TOOL_CALL", "action_name": "search", "action_status": "success"},
    {"agent_id": "a1", "action_type": "TOOL_RESULT", "action_name": "search", "action_status": "success"}
  ]'
```