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

# API Reference

> ProvenLog REST API documentation

All API endpoints are served under the `/v1/` prefix when running `plog serve`.

## Base URL

```
http://localhost:7600/v1
```

## Authentication

When the server is started with `--api-keys`, all endpoints require a Bearer token:

```bash theme={null}
curl -H "Authorization: Bearer your-api-key" http://localhost:7600/v1/events
```

## Endpoints

### Ingest

| Method | Path                                           | Description                                     |
| ------ | ---------------------------------------------- | ----------------------------------------------- |
| `POST` | [`/v1/events`](/api-reference/endpoint/ingest) | Ingest a single event                           |
| `POST` | [`/v1/batch`](/api-reference/endpoint/ingest)  | Ingest multiple events (207 on partial failure) |

### Query

| Method | Path                                              | Description                   |
| ------ | ------------------------------------------------- | ----------------------------- |
| `GET`  | [`/v1/events`](/api-reference/endpoint/query)     | List events with filters      |
| `GET`  | [`/v1/events/:id`](/api-reference/endpoint/query) | Get a single event by ID      |
| `GET`  | [`/v1/search`](/api-reference/endpoint/query)     | Full-text search              |
| `GET`  | [`/v1/agents`](/api-reference/endpoint/query)     | List agents with event counts |
| `GET`  | [`/v1/stats`](/api-reference/endpoint/query)      | Aggregate statistics          |

### Integrity

| Method | Path                                                   | Description               |
| ------ | ------------------------------------------------------ | ------------------------- |
| `GET`  | [`/v1/verify`](/api-reference/endpoint/integrity)      | Verify hash chain         |
| `GET`  | [`/v1/merkle/root`](/api-reference/endpoint/integrity) | Compute Merkle root       |
| `GET`  | [`/v1/export`](/api-reference/endpoint/integrity)      | Export verifiable package |

### Timestamping

| Method | Path                                                          | Description                |
| ------ | ------------------------------------------------------------- | -------------------------- |
| `POST` | [`/v1/timestamp`](/api-reference/endpoint/timestamps)         | Request RFC 3161 timestamp |
| `GET`  | [`/v1/timestamps`](/api-reference/endpoint/timestamps)        | List stored timestamps     |
| `GET`  | [`/v1/timestamps/verify`](/api-reference/endpoint/timestamps) | Verify latest timestamp    |

### Policy

| Method | Path               | Description                               |
| ------ | ------------------ | ----------------------------------------- |
| `POST` | `/v1/policy/check` | Run policy checks against the audit trail |

### Real-time

| Method | Path                                           | Description                 |
| ------ | ---------------------------------------------- | --------------------------- |
| `GET`  | [`/v1/stream`](/api-reference/endpoint/stream) | WebSocket live event stream |

### Other

| Method | Path                   | Description                                    |
| ------ | ---------------------- | ---------------------------------------------- |
| `GET`  | `/v1/dashboard/config` | Dashboard feature configuration                |
| `POST` | `/v1/traces`           | OTLP trace receiver (when `--otlp` is enabled) |

## Error handling

The API uses standard HTTP status codes:

| Status | Description                                     |
| ------ | ----------------------------------------------- |
| `200`  | Success                                         |
| `201`  | Created (single event or full batch success)    |
| `207`  | Multi-status (batch endpoint — partial failure) |
| `400`  | Bad request (validation error)                  |
| `401`  | Unauthorized (missing or invalid API key)       |
| `404`  | Not found                                       |
| `500`  | Internal server error                           |