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

# Browse the Action Catalog — AuditRails API Reference

> Browse the compliance action catalog to discover supported event types, their required metadata fields, and which regulatory frameworks they satisfy.

The List Action Catalog endpoint returns the full set of named actions that AuditRails recognizes for structured compliance logging. Each entry describes what the action represents, which regulatory frameworks it satisfies, and which metadata fields are required or optional when you log an event with that action name. You can call this endpoint without authentication to explore the catalog, or with your API key to see which actions are active for your organization's subscribed frameworks and get a per-action `subscribed` flag.

## Endpoint

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

## Authentication

This endpoint works both with and without an API key:

* **Unauthenticated** — Returns the complete action catalog with all frameworks and fields. The `subscribed` field is not included in unauthenticated responses.
* **Authenticated** — Returns the same catalog filtered to the compliance frameworks active for your organization, plus a `subscribed` boolean on each action indicating whether your plan includes that action.

## Response Fields

<ResponseField name="actions" type="array" required>
  Array of action catalog entries.

  <Expandable title="Action object fields">
    <ResponseField name="action" type="string">
      The canonical action name to use in the `action` field when ingesting events, for example `aiact.model_inference_logged`. Action names are namespaced by compliance domain.
    </ResponseField>

    <ResponseField name="category" type="string">
      High-level category grouping for this action, for example `ai_act` or `auth`. Present when set on the catalog entry.
    </ResponseField>

    <ResponseField name="description" type="string">
      Human-readable explanation of what this action represents and when to use it.
    </ResponseField>

    <ResponseField name="frameworks" type="array">
      List of compliance frameworks this action satisfies.

      <Expandable title="Framework object fields">
        <ResponseField name="framework" type="string">
          Machine-readable framework identifier, for example `eu_ai_act` or `soc2`.
        </ResponseField>

        <ResponseField name="label" type="string">
          Human-readable framework name, for example `EU AI Act` or `SOC 2`.
        </ResponseField>

        <ResponseField name="is_required" type="boolean">
          `true` if logging this action is required to maintain compliance with the framework. `false` if it is recommended but optional.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="required_fields" type="array">
      List of metadata field names that must be present in the `metadata` object when you ingest an event with this action. Omitting any of these fields causes the ingest request to be rejected with a validation error.
    </ResponseField>

    <ResponseField name="optional_fields" type="array">
      List of metadata field names that are recognized and indexed for this action but are not mandatory. Including them enriches your compliance records.
    </ResponseField>

    <ResponseField name="subscribed" type="boolean">
      Whether your organization's current plan includes this action. Only present in authenticated responses.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer" required>
  Total number of actions returned in this response.
</ResponseField>

<Note>
  The `required_fields` list is enforced at ingestion time on `POST /v1/events`. Before logging a new action type in production, retrieve its catalog entry to confirm which metadata fields you need to supply. Sending an event with a missing required field returns a validation error.
</Note>

## Example Request — Unauthenticated

Use the unauthenticated form to browse the full catalog without an API key, for example during integration planning or framework evaluation:

```bash theme={null}
curl https://api.auditrails.io/v1/actions
```

## Example Request — Authenticated

Pass your API key to filter the catalog to your organization's active frameworks and see the `subscribed` flag:

```bash theme={null}
curl https://api.auditrails.io/v1/actions \
  -H "Authorization: Bearer at_live_xxx"
```

## Example Response

```json theme={null}
{
  "actions": [
    {
      "action": "aiact.model_inference_logged",
      "category": "ai_act",
      "description": "Log a single model inference for EU AI Act Article 12 record-keeping.",
      "frameworks": [
        {
          "framework": "eu_ai_act",
          "label": "EU AI Act",
          "is_required": true
        }
      ],
      "required_fields": ["system_id", "model_id"],
      "optional_fields": ["input_hash", "output_hash", "latency_ms", "risk_tier"],
      "subscribed": true
    }
  ],
  "total": 1
}
```

## Using the Catalog for Compliance

Each action entry maps directly to one or more regulatory requirements. The `is_required` flag on each framework entry tells you whether you must log that action to remain compliant, or whether it is a recommended best practice. When building an integration for a specific framework, filter the catalog by framework identifier and focus first on actions where `is_required` is `true`.

The `required_fields` and `optional_fields` arrays define the expected shape of the `metadata` object for each event type. Required fields are validated on every ingest request, so aligning your integration to the catalog before going live prevents unexpected ingest failures.

## Error Responses

| Status | Code                 | Description                                                                                                                    |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `401`  | `auth/key_not_found` | An `Authorization` header was supplied but the API key is invalid. Unauthenticated requests (no header) succeed without a key. |