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

# AuditRails API Overview: Endpoints and Conventions

> A complete reference for the AuditRails REST API — ingest events, query audit logs, verify chain integrity, and explore the compliance action catalog.

The AuditRails API is a REST interface that lets you ingest tamper-proof audit events, retrieve and filter your log history, verify cryptographic chain integrity, and browse the compliance action catalog. All requests are made over HTTPS to the base URL `https://api.auditrails.io`, and every endpoint is versioned under `/v1/`. Request and response bodies use `application/json`.

<Info>
  DSAR (Data Subject Access Request) workflows are available exclusively through the AuditRails dashboard and are not exposed via the bearer-token API.
</Info>

## Base URL

```
https://api.auditrails.io/v1
```

## Request & Response Conventions

Every request must include the `Content-Type: application/json` header alongside your `Authorization` header. Every response — including errors — contains an `X-Request-Id` header in `req_<ULID>` format. Hold on to this value when contacting support; it uniquely identifies the exact server-side transaction.

### Error Format

When a request fails, AuditRails returns a structured error body so you always know what went wrong and where to learn more.

```json theme={null}
{
  "error": {
    "code": "validation/missing_action",
    "message": "The 'action' field is required.",
    "request_id": "req_01HX7YGBFZ3QK8N9VMJT5RPCE4",
    "doc_url": "https://docs.auditrails.io/reference/error-codes"
  }
}
```

| Field        | Type   | Description                                                |
| ------------ | ------ | ---------------------------------------------------------- |
| `code`       | string | Machine-readable error code in `category/slug` format.     |
| `message`    | string | Human-readable explanation of the error.                   |
| `request_id` | string | The same ID present in the `X-Request-Id` response header. |
| `doc_url`    | string | Direct link to the relevant error-code documentation page. |

***

## Endpoint Catalog

The table below lists every available endpoint grouped by functional category. Click an endpoint name to jump to its dedicated reference page.

### Ingestion

| Method | Path                                                   | Description                                              |
| ------ | ------------------------------------------------------ | -------------------------------------------------------- |
| `POST` | [`/v1/events`](/api-reference/post-events)             | Ingest a single audit event into your log.               |
| `POST` | [`/v1/events/batch`](/api-reference/post-events-batch) | Ingest a batch of up to 100 audit events in one request. |

### Read & Query

| Method | Path                                               | Description                                                                    |
| ------ | -------------------------------------------------- | ------------------------------------------------------------------------------ |
| `GET`  | [`/v1/events`](/api-reference/get-events)          | List audit events with optional filters (actor, action, date range, and more). |
| `GET`  | [`/v1/events/{log_id}`](/api-reference/get-event)  | Retrieve a single audit event by its unique log ID.                            |
| `GET`  | [`/v1/events/verify`](/api-reference/verify-chain) | Verify the cryptographic integrity of your audit chain.                        |

### Compliance

| Method | Path                                    | Description                                                           |
| ------ | --------------------------------------- | --------------------------------------------------------------------- |
| `GET`  | [`/v1/actions`](/api-reference/actions) | Fetch the full compliance action catalog (standardised action slugs). |

***

## Quick-Start Example

The snippet below ingests your first event in a single `curl` command. Replace `at_live_xxx` with your production API key.

```bash theme={null}
curl -X POST https://api.auditrails.io/v1/events \
  -H "Authorization: Bearer at_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "user.login",
    "actor_id": "user_123"
  }'
```

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Learn how API keys work, the difference between live and test keys, and how to handle auth errors.
  </Card>

  <Card title="Rate Limits" icon="gauge-high" href="/api-reference/rate-limits">
    Understand per-IP, per-plan, and test-key rate limits, and how to handle 429 responses gracefully.
  </Card>

  <Card title="Error Codes" icon="circle-exclamation" href="/reference/error-codes">
    Browse the full list of machine-readable error codes returned by the API.
  </Card>

  <Card title="SDKs" icon="code" href="/sdks/overview">
    Use an official AuditRails SDK to get automatic retries, typed responses, and more.
  </Card>
</CardGroup>