Audit API¶

The Audit API provides read-only access to the immutable audit trail (INV-001). Every agent action, connector call, policy evaluation, approval decision, and administrative change is recorded as an append-only audit log entry. These endpoints allow querying, retrieving, and exporting audit data.

All endpoints are scoped to the authenticated user's organization via Row-Level Security. No endpoint permits modification or deletion of audit records.

Query Audit Logs¶

Retrieves audit log entries for the organization with optional filtering.

Method: GET
Path: /v1/audit
Required Role: Any authenticated user

Query Parameters¶

Parameter	Type	Required	Description
`agent_id`	`UUID`	No	Filter entries by agent.
`action_type`	`string`	No	Filter by action type (e.g., `connector.called`, `agent.deployed`).
`connector`	`string`	No	Filter by connector type (e.g., `crowdstrike`).
`status`	`string`	No	Filter by status: `success`, `error`, `blocked`.
`limit`	`integer`	No	Number of entries to return (1--1000, default 100).
`offset`	`integer`	No	Pagination offset (default 0).

Response¶

{
  "entries": [
    {
      "id": "entry-uuid",
      "org_id": "org-uuid",
      "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_id": null,
      "action_type": "connector.called",
      "connector": "crowdstrike",
      "target_resource": "detections:read",
      "inputs_hash": "a3f2b8c1d4e5...",
      "outputs_hash": "f7e6d5c4b3a2...",
      "policy_verdict": "PERMIT",
      "duration_ms": 342,
      "status": "success",
      "metadata": { "risk_score": 15, "policy_id": "policy-uuid" },
      "created_at": "2026-04-10T16:30:00Z"
    }
  ],
  "total": 1247
}

Results are ordered by created_at descending (most recent first).

Example¶

curl -X GET "https://api.arxsec.io/v1/audit?agent_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&action_type=connector.called&limit=50" \
  -H "Authorization: Bearer {token}"

Get Audit Entry¶

Retrieves a single audit log entry by ID.

Method: GET
Path: /v1/audit/{entry_id}
Required Role: Any authenticated user

Path Parameters¶

Parameter	Type	Description
`entry_id`	`UUID`	The audit entry's unique identifier.

Example¶

curl -X GET "https://api.arxsec.io/v1/audit/entry-uuid" \
  -H "Authorization: Bearer {token}"

Response¶

Returns the full audit log entry object. Returns 404 if the entry does not exist or belongs to a different organization.

Export Audit Log¶

Exports the audit trail as a downloadable file for compliance evidence, board reports, or SIEM ingestion.

Method: GET
Path: /v1/audit/export
Required Role: Any authenticated user

Query Parameters¶

Parameter	Type	Required	Description
`agent_id`	`UUID`	No	Scope the export to a single agent.
`format`	`string`	No	Export format: `csv` (default) or `json`.
`limit`	`integer`	No	Maximum entries to export (1--50,000, default 10,000).

CSV Format¶

Produces a downloadable CSV file with columns: created_at, action_type, connector, target_resource, policy_verdict, status, user_name, duration_ms. User IDs are resolved to human-readable names.

JSON Format¶

Produces a downloadable JSON file containing full audit log entry objects with all fields.

Example¶

curl -X GET "https://api.arxsec.io/v1/audit/export?format=csv&limit=5000" \
  -H "Authorization: Bearer {token}" \
  -o arxsec-audit-export.csv

curl -X GET "https://api.arxsec.io/v1/audit/export?format=json&agent_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer {token}" \
  -o arxsec-audit-export.json

The response includes a Content-Disposition header with an appropriate filename for the selected format.