# API reference

Documentation owner: module `audit`; documentation version: `next`.
Source: `content/modules/audit/next/api-reference.md` at commit `eaf7a020437971baeee95e87eaf963636040ac71`.

The Audit module exposes a small, read-only REST API over the same event data shown in the [audit UI](/modules/audit/next/using-the-ui/). It is available whether or not the UI itself is enabled — see [headless](/modules/audit/next/#configuration).

## Endpoints

All paths are relative to `{http_context}/api` (`/audit/api` with the default configuration).

| Method | Path | Description |
| --- | --- | --- |
| GET | `/chains` | List events matching the given filters. |
| GET | `/chains/{chainId}` | Get one event, including its change packages and changes. |
| GET | `/changes` | Search individual field-level changes across events. |
| GET | `/openapi.yaml` | The full OpenAPI 3.0 specification for this API, always in sync with the deployed version. |

:::note
"Chain" is the API's name for what the UI calls an event — see [Data model](/modules/audit/next/data-model/).
:::

## Filtering

`GET /chains` accepts `sourceType`, `sourceName`, `initiatorId`, `status`, `from`, and `to` (ISO-8601 instants, matched against the event's start time) as query parameters.

`GET /changes` accepts `objectId`, `objectType`, and `identityId`. `objectId`/`objectType` match the object a change actually targeted; `identityId` matches the change package's identity, which can differ from the object per the routing behavior described under [Enrichment](/modules/audit/next/data-model/#enrichment). Each result includes `chainId` and `identityId`, so a caller can link back to `GET /chains/{chainId}`.

## Response shape

Every response is a JSON envelope:

```json
{
  "success": true,
  "data": { ... }
}
```

On failure, `success` is `false` and `reason` describes what went wrong.

`GET /chains/{chainId}` returns an event with its packages and their changes nested inside. `GET /chains` and `GET /changes` return flat arrays under `data.chains` and `data.changes` respectively. The exact field-by-field shape is defined by the OpenAPI specification at `/openapi.yaml`.

## Pagination and sorting

This is a first iteration of the API: there is no pagination or sorting option yet. `GET /chains` returns every event matching the given filters, newest first.

## Authentication

The API has no built-in authentication by default. See [Authentication](/modules/audit/next/#authentication) for how access is restricted in a deployment.