# Audit log

Generated from contract version `1.0.0` — the same document [`/v1/api/openapi.json`](/api/openapi/) serves.

## Prerequisites

- An API key in `x-api-key`, or a browser session cookie
- `X-Organization-Id` naming the workspace to act in, unless the session already has an active one
- The base URL for your deployment, `https://server.hlix.ai` by default

## Operations

| Method | Path | Operation |
| --- | --- | --- |
| `GET` | `/v1/api/audit-log` | [List the workspace's audit trail](#list-the-workspaces-audit-trail) |
| `GET` | `/v1/api/audit-log/{id}` | [Get one audit entry and its correlated rows](#get-one-audit-entry-and-its-correlated-rows) |
| `GET` | `/v1/api/audit-log/projects/{projectId}` | [List one project's audit trail](#list-one-projects-audit-trail) |
| `GET` | `/v1/api/audit-log/verify` | [Verify the tamper-evidence hash chain](#verify-the-tamper-evidence-hash-chain) |

## List the workspace's audit trail

`GET /v1/api/audit-log` · operation ID `listAuditLog`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | no | string | Page size, clamped to 1–200. Defaults to 50. |
| `cursor` | query | no | string | The previous page's `nextCursor`, verbatim. Opaque — never construct one. |
| `actorType` | query | no | string | `user` \| `api_key` \| `agent` \| `system`. |
| `actorId` | query | no | string | Exact id of the actor. |
| `action` | query | no | string | Exact action name, such as `project.create`. An action the server does not know is IGNORED, not rejected — the page comes back unfiltered. |
| `category` | query | no | string | `create` \| `read` \| `update` \| `delete` \| `execute` \| `auth` \| `export`. |
| `resourceType` | query | no | string | Exact resource type, such as `project`. |
| `resourceId` | query | no | string | Exact resource id. |
| `outcome` | query | no | string | `success` \| `failure` \| `denied`. |
| `severity` | query | no | string | `info` \| `notice` \| `warning` \| `critical`. |
| `source` | query | no | string | Where the action came in: `web` \| `api` \| `cli` \| `telegram` \| `linear` \| `github` \| `webhook` \| `internal` \| `system`. |
| `requestId` | query | no | string | Correlation id of one request. |
| `traceId` | query | no | string | Correlation id shared with the other planes. |
| `from` | query | no | string | Inclusive lower bound on `occurredAt`, ISO. An unparseable value is IGNORED rather than rejected. |
| `to` | query | no | string | Inclusive upper bound on `occurredAt`, ISO. |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | AuditPage | One keyset page of audit rows, newest first. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is not an owner or admin of this workspace — or is not a member of it at all. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Get one audit entry and its correlated rows

`GET /v1/api/audit-log/{id}` · operation ID `getAuditEntry`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `id` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | AuditEntryDetail | The entry, plus the events, agent runs and log lines sharing its trace id. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is not an owner or admin of this workspace — or is not a member of it at all. |
| `404` | ApiError | No such audit entry in this workspace. |

## List one project's audit trail

`GET /v1/api/audit-log/projects/{projectId}` · operation ID `listProjectAuditLog`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `projectId` | path | **yes** | string |  |
| `limit` | query | no | string | Page size, clamped to 1–200. Defaults to 50. |
| `cursor` | query | no | string | The previous page's `nextCursor`, verbatim. Opaque — never construct one. |
| `action` | query | no | string | Exact action name. |
| `actorType` | query | no | string | `user` \| `api_key` \| `agent` \| `system`. |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | AuditPage | A curated projection over the same table: rows where the project IS the resource, is the parent resource, or is named in `metadata.projectId`. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is not an owner or admin of this workspace — or is not a member of it at all. |
| `404` | ApiError | No such project in this workspace. |

## Verify the tamper-evidence hash chain

`GET /v1/api/audit-log/verify` · operation ID `verifyAuditChain`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | AuditChainVerification | The result of walking the chain. A 200 does NOT mean the chain is intact — read `ok`. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is not an owner or admin of this workspace — or is not a member of it at all. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## If a request fails

These apply to every operation on this page.

- `400` — the body failed schema validation, or the request named no active organization. A `ValidationError` body carries the failing fields; an `ApiError` body carries only `error`.
- `401` — no valid session or API key.
- `403` — authenticated, but not a member of the named organization, or a client collaborator without the required access.
- `404` — no such resource **in this workspace**. Absent and not-visible are deliberately the same answer; do not infer cross-tenant existence from it.
- `409` — the expected revision or state is stale, or another operation currently owns the transition.
- `500` — the operation failed server-side. Retry only where an idempotency key makes that safe.

## Next steps

[API reference](/api/reference/)
  [API & OpenAPI](/api/openapi/)
  [TypeScript SDK](/sdk/typescript/)
  [CLI reference](/reference/cli/)