Audit API

Endpoints for the immutable audit trail. Every governance decision made by Sentinel is recorded as a sequenced, hash-chained audit record. The hash chain ensures tamper-evidence — any modification to a past record breaks the chain and is detectable via the verification endpoint.

Endpoints

Method	Path	Description
GET	`/audit`	List audit records
GET	`/audit/:seq`	Get a specific audit record
GET	`/audit/verify`	Verify hash chain integrity
GET	`/audit/export`	Export audit trail (PDF or CSV)

Audit Record Structure

Every audit record contains the following fields:

Field	Type	Description
`seq`	`integer`	Monotonically increasing sequence number
`timestamp`	`string`	ISO 8601 timestamp of the governance decision
`agent_id`	`string`	The agent that requested the action
`action_type`	`string`	Type of action (READ, WRITE, EXECUTE, DELETE, etc.)
`target`	`string`	Resource the action targeted
`environment`	`string`	Environment (production, staging, development)
`confidence`	`number`	Agent's confidence score (0.0 to 1.0)
`verdict`	`string`	Sentinel's decision: `ALLOW`, `ESCROW`, `DENY`
`policies_evaluated`	`integer`	Number of CHAM policies checked
`policies_fired`	`array`	Policies that triggered on this action
`tier`	`string`	Governance tier at time of decision
`reasoning`	`string`	Agent's reasoning for the action
`hash`	`string`	SHA-256 hash of this record
`prev_hash`	`string`	SHA-256 hash of the previous record (forms the chain)
`chain_position`	`integer`	Position in the hash chain

GET /audit

List audit records with filtering and pagination.

Query Parameters

Parameter	Type	Default	Description
`page`	`integer`	`1`	Page number
`limit`	`integer`	`50`	Results per page (max 200)
`start_date`	`string`	—	ISO 8601 start date filter
`end_date`	`string`	—	ISO 8601 end date filter
`agent`	`string`	—	Filter by agent ID
`verdict`	`string`	—	Filter by verdict: `ALLOW`, `ESCROW`, `DENY`
`tier`	`string`	—	Filter by governance tier
`action_type`	`string`	—	Filter by action type

Example Request

bash

curl -X GET "https://api.thewardn.ai/audit?verdict=DENY&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "records": [
    {
      "seq": 10847,
      "timestamp": "2026-04-10T14:00:00Z",
      "agent_id": "agent_sales_bot",
      "action_type": "WRITE",
      "target": "customer_records",
      "environment": "production",
      "confidence": 0.72,
      "verdict": "ESCROW",
      "policies_evaluated": 6,
      "policies_fired": [
        {
          "policy_id": "pol_8f3a2b1c",
          "policy_name": "Production Confidence Floor",
          "reason": "Confidence 0.72 is below threshold 0.85"
        }
      ],
      "tier": "business",
      "reasoning": "Bulk pricing update based on Q2 pricing sheet.",
      "hash": "a3f8c2e1d4b7...sha256",
      "prev_hash": "e7d1b3a9f5c2...sha256",
      "chain_position": 10847
    },
    {
      "seq": 10846,
      "timestamp": "2026-04-10T13:55:12Z",
      "agent_id": "agent_deploy_bot",
      "action_type": "EXECUTE",
      "target": "deployment_pipeline",
      "environment": "production",
      "confidence": 0.95,
      "verdict": "ALLOW",
      "policies_evaluated": 6,
      "policies_fired": [],
      "tier": "business",
      "reasoning": "Deploy v2.4.0 hotfix for checkout bug. All tests green.",
      "hash": "e7d1b3a9f5c2...sha256",
      "prev_hash": "b2c4d6e8f0a1...sha256",
      "chain_position": 10846
    }
  ],
  "total": 10847,
  "page": 1,
  "limit": 10
}

GET /audit/:seq

Get a specific audit record by its sequence number.

Path Parameters

Parameter	Type	Description
`seq`	`integer`	Audit record sequence number

Example Request

bash

curl -X GET https://api.thewardn.ai/audit/10847 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "seq": 10847,
  "timestamp": "2026-04-10T14:00:00Z",
  "agent_id": "agent_sales_bot",
  "action_type": "WRITE",
  "target": "customer_records",
  "environment": "production",
  "confidence": 0.72,
  "verdict": "ESCROW",
  "policies_evaluated": 6,
  "policies_fired": [
    {
      "policy_id": "pol_8f3a2b1c",
      "policy_name": "Production Confidence Floor",
      "policy_type": "confidence_floor",
      "reason": "Confidence 0.72 is below threshold 0.85"
    },
    {
      "policy_id": "pol_d4f6a8c0",
      "policy_name": "Bulk Write Gate",
      "policy_type": "rate_limit",
      "reason": "Batch size 847 exceeds single-action limit of 100"
    }
  ],
  "tier": "business",
  "reasoning": "Bulk pricing update based on Q2 pricing sheet.",
  "escrow_id": "esc_7a2b3c4d",
  "escrow_outcome": "RELEASED",
  "hash": "a3f8c2e1d4b756901fcd3e8a72b4f19d0e6c5a83b7d2f104e9a8c3b6d5f07e21",
  "prev_hash": "e7d1b3a9f5c28e4d0a1b3c5d7f9e2a4b6c8d0e2f4a6b8c0d2e4f6a8b0c2d4e6",
  "chain_position": 10847
}

GET /audit/verify

Verify the integrity of the hash chain. This endpoint walks the chain and confirms that every record's prev_hash matches the hash of the preceding record. Any tampering is detected and reported.

Query Parameters

Parameter	Type	Default	Description
`start_seq`	`integer`	`1`	Start verification from this sequence number
`end_seq`	`integer`	latest	End verification at this sequence number

Example Request

bash

curl -X GET https://api.thewardn.ai/audit/verify \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response — Chain Intact

json

{
  "verified": true,
  "chain_length": 10847,
  "start_seq": 1,
  "end_seq": 10847,
  "verified_at": "2026-04-10T14:50:00Z",
  "elapsed_ms": 1243
}

Example Response — Chain Broken

json

{
  "verified": false,
  "chain_length": 10847,
  "start_seq": 1,
  "end_seq": 10847,
  "break_detected_at": 5023,
  "expected_hash": "a1b2c3d4e5f6...",
  "actual_hash": "f6e5d4c3b2a1...",
  "verified_at": "2026-04-10T14:50:00Z",
  "elapsed_ms": 587
}

DANGER

A broken hash chain indicates tampering. If verification fails, immediately investigate the records around the break point. The audit trail is your regulatory proof — a broken chain undermines compliance claims.

GET /audit/export

Export the audit trail in PDF or CSV format. Useful for compliance audits, board reports, and regulatory submissions.

Query Parameters

Parameter	Type	Default	Description
`format`	`string`	`pdf`	Export format: `pdf` or `csv`
`start_date`	`string`	—	ISO 8601 start date
`end_date`	`string`	—	ISO 8601 end date
`agent`	`string`	—	Filter by agent ID
`verdict`	`string`	—	Filter by verdict

Example Request — PDF Export

bash

curl -X GET "https://api.thewardn.ai/audit/export?format=pdf&start_date=2026-04-01&end_date=2026-04-10" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o audit_report.pdf

Example Request — CSV Export

bash

curl -X GET "https://api.thewardn.ai/audit/export?format=csv&start_date=2026-04-01&end_date=2026-04-10" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o audit_report.csv

Response

The response is a binary file download with the appropriate content type:

PDF: Content-Type: application/pdf
CSV: Content-Type: text/csv

TIP

For large date ranges, the export may take several seconds. The response includes a Content-Disposition header with a suggested filename, e.g., audit_2026-04-01_2026-04-10.pdf.

Audit API ​

Endpoints ​

Audit Record Structure ​

GET /audit ​

Query Parameters ​

Example Request ​

Example Response ​

GET /audit/:seq ​

Path Parameters ​

Example Request ​

Example Response ​

GET /audit/verify ​

Query Parameters ​

Example Request ​

Example Response — Chain Intact ​

Example Response — Chain Broken ​

GET /audit/export ​

Query Parameters ​

Example Request — PDF Export ​

Example Request — CSV Export ​

Response ​

Audit API

Endpoints

Audit Record Structure

GET /audit

Query Parameters

Example Request

Example Response

GET /audit/:seq

Path Parameters

Example Request

Example Response

GET /audit/verify

Query Parameters

Example Request

Example Response — Chain Intact

Example Response — Chain Broken

GET /audit/export

Query Parameters

Example Request — PDF Export

Example Request — CSV Export

Response