AuditRails API Overview: Endpoints and Conventions

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.

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

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.

{
  "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`	Ingest a single audit event into your log.
`POST`	`/v1/events/batch`	Ingest a batch of up to 100 audit events in one request.

Read & Query

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

Compliance

Method	Path	Description
`GET`	`/v1/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.

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

Authentication

Learn how API keys work, the difference between live and test keys, and how to handle auth errors.

Rate Limits

Understand per-IP, per-plan, and test-key rate limits, and how to handle 429 responses gracefully.

Error Codes

Browse the full list of machine-readable error codes returned by the API.

SDKs

Use an official AuditRails SDK to get automatic retries, typed responses, and more.

Overview

Ingestion

Read & Verify

Data Subject Requests

AuditRails API Overview: Endpoints and Conventions

Base URL

Request & Response Conventions

Error Format

Endpoint Catalog

Ingestion

Read & Query

Compliance

Quick-Start Example

Authentication

Rate Limits

Error Codes

SDKs

​Base URL

​Request & Response Conventions

​Error Format

​Endpoint Catalog

​Ingestion

​Read & Query

​Compliance

​Quick-Start Example

Authentication

Rate Limits

Error Codes

SDKs

Base URL

Request & Response Conventions

Error Format

Endpoint Catalog

Ingestion

Read & Query

Compliance

Quick-Start Example