Evidence & Discovery

Create sealed evidence packages and run audited point-in-time queries — Phase 3 of the Aira accountability stack.

All endpoints require a Bearer token (Authorization: Bearer aira_live_xxxxx). Base URL: https://api.airaproof.com/api/v1

Create Evidence Package

POST /api/v1/evidence/packages
Authorization: Bearer aira_live_xxxxx

Creates a sealed, tamper-proof evidence package from a set of action UUIDs. The package bundles all referenced actions, their receipts, chain-of-custody records, and agent metadata into a single cryptographically signed artifact.

Request Body

Field	Type	Required	Description
`action_uuids`	string[]	Yes	Action UUIDs to include in the package
`title`	string	Yes	Descriptive title for the package
`purpose`	string	No	Purpose of the package (e.g. `litigation`, `regulatory_response`, `internal_audit`)
`metadata`	object	No	Arbitrary metadata to attach

Example Request

curl -X POST https://api.airaproof.com/api/v1/evidence/packages \
  -H "Authorization: Bearer aira_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "action_uuids": ["act_01J9B...", "act_01J9C...", "act_01J9D..."],
    "title": "Vendor payment audit Q1 2026",
    "purpose": "internal_audit",
    "metadata": {
      "auditor": "external-compliance-team"
    }
  }'

Response (201 Created)

{
  "package_uuid": "pkg_01J9E...",
  "title": "Vendor payment audit Q1 2026",
  "purpose": "internal_audit",
  "status": "sealed",
  "action_count": 3,
  "package_hash": "sha256:d4e5f6a7...",
  "signature": "ed25519:base64url...",
  "public_key_id": "aira-signing-key-v1",
  "sealed_at": "2026-03-24T16:00:00.000Z",
  "created_by": "user_01J9C...",
  "request_id": "req_01J9E..."
}

Error Codes

Status	Code	Description
400	`EMPTY_ACTION_LIST`	At least one action UUID is required
404	`ACTION_NOT_FOUND`	One or more action UUIDs do not exist
422	`CROSS_ORG_ACTIONS`	All actions must belong to the same organization

List Evidence Packages

GET /api/v1/evidence/packages?page=1&per_page=20
Authorization: Bearer aira_live_xxxxx

Returns a paginated list of evidence packages.

Response (200 OK)

{
  "packages": [
    {
      "package_uuid": "pkg_01J9E...",
      "title": "Vendor payment audit Q1 2026",
      "purpose": "internal_audit",
      "status": "sealed",
      "action_count": 3,
      "sealed_at": "2026-03-24T16:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 8
  }
}

Get Evidence Package

GET /api/v1/evidence/packages/{package_uuid}
Authorization: Bearer aira_live_xxxxx

Returns the full evidence package including all bundled actions, receipts, and chain-of-custody records.

Response (200 OK)

{
  "package_uuid": "pkg_01J9E...",
  "title": "Vendor payment audit Q1 2026",
  "purpose": "internal_audit",
  "status": "sealed",
  "package_hash": "sha256:d4e5f6a7...",
  "signature": "ed25519:base64url...",
  "public_key_id": "aira-signing-key-v1",
  "actions": [
    {
      "action_uuid": "act_01J9B...",
      "action_type": "transaction",
      "agent_id": "procurement-agent",
      "status": "authorized",
      "receipt": { "...": "..." },
      "chain": [ "..." ],
      "created_at": "2026-03-24T14:30:00.000Z"
    }
  ],
  "metadata": {
    "auditor": "external-compliance-team"
  },
  "sealed_at": "2026-03-24T16:00:00.000Z",
  "created_by": "user_01J9C..."
}

Time-Travel Query

POST /api/v1/evidence/time-travel
Authorization: Bearer aira_live_xxxxx

Runs a point-in-time query against the action ledger. Every time-travel query is itself audited — a discovery_query record is created so you have a trail of who queried what and when.

Request Body

Field	Type	Required	Description
`query`	object	Yes	Query filters (see below)
`point_in_time`	string	Yes	ISO 8601 timestamp — results reflect state as of this moment
`reason`	string	Yes	Why this query is being run (recorded in audit trail)

Query Filters

Field	Type	Description
`query.agent_id`	string	Filter by agent
`query.action_type`	string	Filter by action type
`query.date_from`	string	Start of date range (ISO 8601)
`query.date_to`	string	End of date range (ISO 8601)
`query.status`	string	Filter by status

Example Request

curl -X POST https://api.airaproof.com/api/v1/evidence/time-travel \
  -H "Authorization: Bearer aira_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "agent_id": "procurement-agent",
      "action_type": "transaction",
      "date_from": "2026-01-01T00:00:00Z",
      "date_to": "2026-03-01T00:00:00Z"
    },
    "point_in_time": "2026-03-15T00:00:00Z",
    "reason": "Q1 regulatory review — investigating vendor payments"
  }'

Response (200 OK)

{
  "discovery_query_uuid": "dq_01J9F...",
  "point_in_time": "2026-03-15T00:00:00Z",
  "reason": "Q1 regulatory review — investigating vendor payments",
  "results": [
    {
      "action_uuid": "act_01J9B...",
      "action_type": "transaction",
      "agent_id": "procurement-agent",
      "status": "authorized",
      "created_at": "2026-02-10T09:15:00.000Z"
    }
  ],
  "result_count": 47,
  "queried_at": "2026-03-24T16:30:00.000Z",
  "queried_by": "user_01J9C..."
}

Error Codes

Status	Code	Description
400	`MISSING_REASON`	A reason is required for all time-travel queries
400	`FUTURE_TIMESTAMP`	`point_in_time` cannot be in the future

Liability Chain

GET /api/v1/evidence/liability-chain/{action_uuid}
Authorization: Bearer aira_live_xxxxx

Traces the multi-hop liability chain for an action. Walks parent_action_uuid references to build a complete picture of which agents, models, and humans were involved in the decision chain leading to this action.

Response (200 OK)

{
  "action_uuid": "act_01J9D...",
  "liability_chain": [
    {
      "hop": 1,
      "action_uuid": "act_01J9D...",
      "action_type": "transaction",
      "agent_id": "procurement-agent",
      "model_id": "claude-opus-4-6",
      "authorized_by": "user_01J9C...",
      "created_at": "2026-03-24T14:30:00.000Z"
    },
    {
      "hop": 2,
      "action_uuid": "act_01J9C...",
      "action_type": "decision",
      "agent_id": "procurement-agent",
      "model_id": "gpt-5.4",
      "authorized_by": null,
      "created_at": "2026-03-24T14:25:00.000Z"
    },
    {
      "hop": 3,
      "action_uuid": "act_01J9A...",
      "action_type": "tool_call",
      "agent_id": "vendor-scoring-agent",
      "model_id": "claude-sonnet-4-6",
      "authorized_by": null,
      "created_at": "2026-03-24T14:20:00.000Z"
    }
  ],
  "total_hops": 3,
  "root_action_id": "act_01J9A..."
}

Error Codes

Status	Code	Description
404	`ACTION_NOT_FOUND`	Action does not exist

Evidence & Discovery

On this page