# HITL Audit Log

> **Warning:** This API is currently a work in progress. The contract may change, and features are subject to updates. Please refer to the documentation regularly for the latest information.

## Overview

The HITL (Human-in-the-Loop) Audit Log API provides read-only access to persistent records of all HITL decisions made within the AI Agent Platform. This API enables compliance teams, security auditors, and operators to review past approval decisions with complete context.

***

## Authentication

All endpoints require authentication via API key in the request header:

```http
X-API-Key: your_api_key_here
```

Access Control

* Tenant Isolation: Users can only access audit records within their organization
* Access Level: Single access level for all authenticated users (no role differentiation)
* Master API Key: System administrators with master API key can access all records

***

{% stepper %}
{% step %}

### List Audit Records

Retrieve a paginated list of HITL audit log records with optional filtering and sorting.

Endpoint: `GET /agents/hitl/audit`

Query Parameters

| Parameter       | Type            | Required | Default | Constraints / Notes                                                                 |
| --------------- | --------------- | -------- | ------- | ----------------------------------------------------------------------------------- |
| `page`          | `integer`       | No       | `1`     | Min: 1. Page number for 1-based pagination.                                         |
| `limit`         | `integer`       | No       | `50`    | Min: 1, Max: 100. Number of records per page.                                       |
| `start_date`    | `string`        | No       | -       | ISO8601 format. Filter records from this date/time (inclusive).                     |
| `end_date`      | `string`        | No       | -       | ISO8601 format. Filter records until this date/time (inclusive).                    |
| `decision_type` | `string` (enum) | No       | -       | One of \[`approved`, `rejected`, `skipped`, `timeout`]. Filter by decision outcome. |
| `agent_id`      | `string` (UUID) | No       | -       | Agent identifier. Filter records for a specific agent.                              |
| `sort_order`    | `string` (enum) | No       | `desc`  | One of \[`asc`, `desc`]. Sort by timestamp in ascending or descending order.        |

Request Example

```http
GET /agents/hitl/audit?page=1&limit=20&decision_type=approved&start_date=2025-10-01T00:00:00Z&sort_order=desc
X-API-Key: your_api_key_here
```

Success Response (200 OK)

{% code title="Response" %}

```json
{
  "success": true,
  "message": "Successfully retrieved 20 of 342 HITL audit records",
  "data": [
    {
      "request_id": "hitl-req-123e4567-e89b-12d3-a456-426614174000",
      "decision": "approved",
      "timestamp": "2025-10-10T14:30:45.123Z",
      "agent": {
        "id": "weekly-report-agent",
        "name": "Weekly Report Generator"
      },
      "tool": {
        "name": "github_create_issue",
        "arguments": {
          "owner": "myorg",
          "repo": "myrepo",
          "title": "Weekly Report - Week 41"
        }
      },
      "metadata": {}
    }
  ],
  "total": 342,
  "page": 1,
  "limit": 20,
  "has_next": true,
  "has_prev": false
}
```

{% endcode %}

Schema: HITLAuditListResponse

Returned by `GET /agents/hitl/audit` list operations.

Response Wrapper

| Field      | Type                     | Description                                  |
| ---------- | ------------------------ | -------------------------------------------- |
| `success`  | `boolean`                | Indicates if the operation was successful    |
| `message`  | `string`                 | Human-readable message describing the result |
| `data`     | `array<HITLAuditRecord>` | Array of HITL audit record objects           |
| `total`    | `integer`                | Total number of records matching the query   |
| `page`     | `integer`                | Current page number (1-based)                |
| `limit`    | `integer`                | Maximum records per page                     |
| `has_next` | `boolean`                | Whether there is a next page available       |
| `has_prev` | `boolean`                | Whether there is a previous page available   |

HITLAuditRecord (List Item)

Each item in the `data` array contains the following fields:

| Field        | Type               | Description                                                              |
| ------------ | ------------------ | ------------------------------------------------------------------------ |
| `request_id` | `string`           | Unique identifier for the HITL request                                   |
| `decision`   | `string` (enum)    | Decision outcome. One of \[`approved`, `rejected`, `skipped`, `timeout`] |
| `timestamp`  | `string` (ISO8601) | When the decision was made                                               |
| `agent`      | `object`           | Agent information (contains: `id`, `name`)                               |
| `tool`       | `object`           | Tool information (contains: `name`, `arguments`)                         |
| `metadata`   | `object`           | Dynamic object for additional context. Empty by default.                 |

Agent Info Structure

| Field  | Type            | Description               |
| ------ | --------------- | ------------------------- |
| `id`   | `string` (UUID) | Agent identifier          |
| `name` | `string`        | Human-readable agent name |

Tool Info Structure

| Field       | Type     | Description                                                                 |
| ----------- | -------- | --------------------------------------------------------------------------- |
| `name`      | `string` | Name of the tool requiring approval                                         |
| `arguments` | `object` | Complete parameters that were passed to the tool. Structure varies by tool. |

Metadata Structure

The `metadata` field is a dynamic object that can contain additional context about the HITL decision.

Note: The metadata object is empty (`{}`) by default. It can be populated with any additional fields based on the specific requirements or information available at the time of the HITL decision.

Error Responses

* 400 Bad Request - Invalid query parameters

```json
{
  "error": "invalid_parameter",
  "message": "Invalid sort_order. Must be either 'asc' or 'desc'",
  "details": {
    "parameter": "sort_order",
    "value": "invalid_value"
  }
}
```

* 401 Unauthorized - Missing or invalid API key

```json
{
  "error": "unauthorized",
  "message": "Authentication required to access audit logs"
}
```

* 403 Forbidden - User lacks permission

```json
{
  "error": "forbidden",
  "message": "User does not have permission to access audit logs"
}
```

* 422 Unprocessable Entity - Invalid date range

```json
{
  "error": "validation_error",
  "message": "Invalid date range: start_date must be before end_date",
  "details": {
    "start_date": "2025-10-10T00:00:00Z",
    "end_date": "2025-10-01T00:00:00Z"
  }
}
```

{% endstep %}

{% step %}

### Get Audit Record Detail

Retrieve detailed information about a specific HITL decision, including the complete payload and metadata.

Endpoint: `GET /agents/hitl/audit/{request_id}`

Path Parameters

| Parameter    | Type   | Required | Description                        |
| ------------ | ------ | -------- | ---------------------------------- |
| `request_id` | string | Yes      | The unique HITL request identifier |

Request Example

```http
GET /agents/hitl/audit/hitl-req-123e4567-e89b-12d3-a456-426614174000
X-API-Key: your_api_key_here
```

Success Response (200 OK)

{% code title="Response" %}

```json
{
  "success": true,
  "message": "HITL audit record retrieved successfully",
  "data": {
    "request_id": "hitl-req-123e4567-e89b-12d3-a456-426614174000",
    "decision": "approved",
    "timestamp": "2025-10-10T14:30:45.123Z",
    "agent": {
      "id": "weekly-report-agent",
      "name": "Weekly Report Generator"
    },
    "tool": {
      "name": "github_create_issue",
      "arguments": {
        "owner": "myorg",
        "repo": "myrepo",
        "title": "Weekly Report - Week 41",
        "body": "## Summary\n\nWeekly activity report...",
        "labels": ["automated", "report"]
      }
    },
    "metadata": {
    }
  }
}
```

{% endcode %}

Schema: HITLAuditDetailResponse

Returned by `GET /agents/hitl/audit/{request_id}` for single record retrieval.

Response Wrapper

| Field     | Type              | Description                                  |
| --------- | ----------------- | -------------------------------------------- |
| `success` | `boolean`         | Indicates if the operation was successful    |
| `message` | `string`          | Human-readable message describing the result |
| `data`    | `HITLAuditRecord` | The complete HITL audit record object        |

HITLAuditRecord (Detail View)

The detail view includes all fields from the list view. The structure is identical to the list item format.

| Field        | Type               | Description                                                              |
| ------------ | ------------------ | ------------------------------------------------------------------------ |
| `request_id` | `string`           | Unique identifier for the HITL request                                   |
| `decision`   | `string` (enum)    | Decision outcome. One of \[`approved`, `rejected`, `skipped`, `timeout`] |
| `timestamp`  | `string` (ISO8601) | When the decision was made                                               |
| `agent`      | `object`           | Agent information (contains: `id`, `name`)                               |
| `tool`       | `object`           | Tool information (contains: `name`, `arguments`)                         |
| `metadata`   | `object`           | Dynamic object for additional context. Can contain any custom fields.    |

Error Responses

* 404 Not Found - Record does not exist

```json
{
  "error": "not_found",
  "message": "Audit log record not found",
  "details": {
    "request_id": "hitl-req-invalid"
  }
}
```

* 401 Unauthorized - Missing or invalid API key

```json
{
  "error": "unauthorized",
  "message": "Authentication required to access audit logs"
}
```

* 403 Forbidden - User lacks permission to access this record

```json
{
  "error": "forbidden",
  "message": "User does not have permission to access this audit record"
}
```

{% endstep %}
{% endstepper %}

***

## Validation Rules

Query Parameters

* `page` must be a positive integer (min: 1)
* `limit` must be between 1 and 100 (inclusive)
* `start_date` and `end_date` must be valid ISO8601 datetime strings
* `end_date` must be after `start_date` when both are provided
* `decision_type` must be one of: `approved`, `rejected`, `skipped`, `timeout`
* `agent_id` must be a valid UUID when provided
* `sort_order` must be either `asc` or `desc`

<details>

<summary>Validation error codes and causes</summary>

| Status | Error             | Cause                                                   |
| ------ | ----------------- | ------------------------------------------------------- |
| `400`  | Invalid parameter | Malformed query parameters or constraint violations     |
| `401`  | Unauthorized      | Missing or invalid API key                              |
| `403`  | Forbidden         | User lacks permission to access audit logs              |
| `404`  | Not found         | Audit record with specified `request_id` does not exist |
| `422`  | Validation error  | Invalid date range (start\_date after end\_date)        |

</details>

***

## Usage Examples

Minimal Query

```http
GET /agents/hitl/audit
X-API-Key: your_api_key_here
```

Full Query with Filters

Retrieve approved decisions for a specific agent in the last 30 days, sorted oldest first:

```http
GET /agents/hitl/audit?page=1&limit=50&decision_type=approved&agent_id=weekly-report-agent&start_date=2025-09-10T00:00:00Z&end_date=2025-10-10T23:59:59Z&sort_order=asc
X-API-Key: your_api_key_here
```

Common Patterns

* Filtering by Date Range:

```http
GET /agents/hitl/audit?start_date=2025-10-01T00:00:00Z&end_date=2025-10-31T23:59:59Z
```

* Filtering by Decision Type:

```http
GET /agents/hitl/audit?decision_type=approved
```

* Filtering by Agent:

```http
GET /agents/hitl/audit?agent_id=weekly-report-agent
```

* Pagination:

```http
GET /agents/hitl/audit?page=2&limit=50
```

* Sorting:

```http
GET /agents/hitl/audit?sort_order=asc
```

Default sorting is descending (newest first).

* Combined Filters:

```http
GET /agents/hitl/audit?decision_type=rejected&agent_id=data-processor-agent&start_date=2025-10-03T00:00:00Z
```

***

## Important Notes

{% hint style="warning" %}
Read-Only API: All audit log endpoints are read-only (GET requests only). Audit records cannot be modified or deleted after creation to ensure audit integrity and compliance.
{% endhint %}

***

## Related Endpoints

HITL Decision Endpoint

To make a HITL decision (which creates an audit record):

Endpoint: `POST /agents/hitl/decision`

Request Body:

{% code title="Request" %}

```json
{
  "request_id": "hitl-req-123e4567-e89b-12d3-a456-426614174000",
  "decision": "approved",
  "operator_input": "Approved after review",
  "run_id": "run-789xyz"
}
```

{% endcode %}

This endpoint triggers the persistence of the audit record that can later be queried via the audit log API.

***

## Related Documentation

* REST API: HITL — Endpoint reference for making HITL decisions
* SDK Reference — Method signatures and usage patterns
* Compliance Guide — Using audit logs for regulatory reporting
