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:

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

---

1

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

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)

Response

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

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

{
  "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

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

• 403 Forbidden - User lacks permission

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

• 422 Unprocessable Entity - Invalid date range

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

2

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

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

Success Response (200 OK)

Response

{
  "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": {
    }
  }
}

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

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

• 401 Unauthorized - Missing or invalid API key

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

• 403 Forbidden - User lacks permission to access this record

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

---

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

Validation error codes and causes

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)

---

Usage Examples

Minimal Query

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:

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:

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

• Filtering by Decision Type:

GET /agents/hitl/audit?decision_type=approved

• Filtering by Agent:

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

• Pagination:

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

• Sorting:

GET /agents/hitl/audit?sort_order=asc

Default sorting is descending (newest first).

• Combined Filters:

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

---

Important Notes

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.

---

Related Endpoints

HITL Decision Endpoint

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

Endpoint: POST /agents/hitl/decision

Request Body:

Request

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

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