API Reference

Audit Events API

Read, write, and verify events in your organisation's cryptographic audit chain. All writes are append-only and cannot be modified or deleted.

Last updated: 2 March 2026

Base URL

https://api.audital.ai/v1

Endpoints

Method	Path	Description
GET	/audit	List audit events with filters and pagination
GET	/audit/:id	Retrieve a single audit event by ID
POST	/audit	Write a new audit event to the chain
POST	/audit/verify	Verify the cryptographic integrity of an event

GET/audit

Returns a paginated list of audit events for your organisation. Results are sorted bychainPosition descending (most recent first).

Query parameters

Parameter	Type	Description
`modelId`	string	Filter to events for a specific model ID
`eventType`	string	Filter by event type (e.g. INFERENCE, DEPLOYMENT)
`severity`	string	Filter by severity: INFO, MEDIUM, HIGH, CRITICAL
`from`	ISO 8601	Start of date range (inclusive)
`to`	ISO 8601	End of date range (inclusive)
`source`	string	Filter by event source: API, GITHUB, JIRA, AWS_SAGEMAKER
`tags`	string[]	Filter by tags (comma-separated)
`limit`	integer	Page size (default: 25, max: 100)
`cursor`	string	Cursor for next page (from previous response pagination.nextCursor)

bash

curl "https://api.audital.ai/v1/audit?modelId=mdl_abc123&limit=25&eventType=INFERENCE" \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxx"

json

{
  "data": [
    {
      "id": "evt_01HZABCDEF1234567890ABCD",
      "chainPosition": 4821,
      "blockHash": "sha256:7c4a8d09ca3762af61e59520943dc26494f8941b",
      "previousHash": "sha256:e3b0c44298fc1c149afb4c8996fb92427ae41e4649",
      "timestamp": "2026-03-02T10:14:33.821Z",
      "eventType": "INFERENCE",
      "severity": "INFO",
      "modelId": "mdl_abc123",
      "source": "API",
      "actor": {
        "type": "SERVICE",
        "id": "svc_scorer_api"
      },
      "payload": {
        "inputHash": "sha256:e3b0c44298fc1c149afb...",
        "outputHash": "sha256:a87ff679a2f3e71d9181...",
        "latencyMs": 142,
        "confidence": 0.97
      },
      "tags": [],
      "verified": true
    }
  ],
  "pagination": {
    "total": 4821,
    "limit": 25,
    "offset": 0,
    "hasMore": true,
    "nextCursor": "cur_01HZABCDEF9876543210WXYZ"
  }
}

Rate limit: 100 req/min (Starter) · 500 req/min (Professional) · Custom (Founding Partner)

GET/audit/:id

Retrieve a single audit event by its ID. Returns the full event payload including chain hashes, actor information, and any linked tickets.

bash

curl https://api.audital.ai/v1/audit/evt_01HZABCDEF1234567890ABCD \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxx"

Status codes

Status	Meaning
200	Event found and returned
401	Invalid or missing API key
403	API key does not have audit:read scope
404	Event ID not found in this organisation

POST/audit

Append a new audit event to your organisation's hash chain. The event is written atomically — the chain position and block hash are returned in the response.

Request body

Field	Type	Description
`modelId`required	string	ID of the registered model this event belongs to
`eventType`required	string	One of: INFERENCE, TRAINING_STARTED, TRAINING_COMPLETED, DEPLOYMENT, CONFIG_CHANGE, DATA_ACCESS, HUMAN_REVIEW, ALERT, SHADOW_AI_DETECTED
`payload`required	object	Arbitrary JSON payload describing the event. Hash-sensitive fields should be pre-hashed with SHA-256.
`severity`	string	INFO (default), MEDIUM, HIGH, or CRITICAL
`actor`	object	Who or what triggered the event: { type, id, displayName?, ipAddress? }
`tags`	string[]	Array of tag strings for filtering (max 10 per event)
`metadata`	object	Additional key-value metadata stored alongside but not hashed into the block
`timestamp`	ISO 8601	Override event timestamp (default: server time at receipt)

bash

curl -X POST https://api.audital.ai/v1/audit \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ide_01HZABCDEF1234567890ABCD" \
  -d '{
    "modelId": "mdl_abc123",
    "eventType": "INFERENCE",
    "severity": "INFO",
    "payload": {
      "inputHash": "sha256:e3b0c44298fc1c149afb4c8996fb92427ae41e4649b934ca495991b7852b855",
      "outputHash": "sha256:a87ff679a2f3e71d9181a67b7542122c",
      "latencyMs": 142,
      "confidence": 0.97,
      "decisionOutput": "APPROVED"
    },
    "actor": {
      "type": "SERVICE",
      "id": "svc_scoring_api",
      "ipAddress": "10.0.1.45"
    },
    "tags": ["credit-risk", "high-value"],
    "metadata": {
      "requestId": "req_xyz789",
      "customerId": "cust_001"
    }
  }'

json

{
  "id": "evt_01HZABCDEF1234567890ABCD",
  "chainPosition": 4822,
  "blockHash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b",
  "previousHash": "sha256:7c4a8d09ca3762af61e59520943dc26494f8941b",
  "timestamp": "2026-03-02T10:14:33.821Z",
  "eventType": "INFERENCE",
  "verified": true
}

POST/audit/verify

Cryptographically verify that a specific event has not been tampered with. Audital recomputes the block hash from the stored payload and compares it to the hash recorded in the chain.

bash

curl -X POST https://api.audital.ai/v1/audit/verify \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "evt_01HZABCDEF1234567890ABCD",
    "expectedHash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b"
  }'

Success response (valid)

json

{
  "eventId": "evt_01HZABCDEF1234567890ABCD",
  "valid": true,
  "chainPosition": 4822,
  "blockHash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b",
  "previousHash": "sha256:7c4a8d09ca3762af61e59520943dc26494f8941b",
  "verifiedAt": "2026-03-02T15:00:00.000Z"
}

Failure response (tampered)

json

{
  "eventId": "evt_01HZABCDEF1234567890ABCD",
  "valid": false,
  "error": "hash_mismatch",
  "message": "Stored block hash does not match recomputed hash. Event data may have been tampered with.",
  "storedHash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b",
  "computedHash": "sha256:0000000000000000000000000000000000000000",
  "verifiedAt": "2026-03-02T15:00:00.000Z"
}

Chain Status API →Webhooks →Authentication →