API Reference

Chain Status API

Monitor and verify the integrity of your organisation's hash chain. Audital verifies the chain automatically every 60 seconds; these endpoints let you trigger verification on demand and integrate chain health into your own monitoring systems.

Last updated: 2 March 2026

Base URL

https://api.audital.ai/v1

Endpoints

Method	Path	Description
GET	/audit/chain-status	Get overall chain integrity status
GET	/audit/chain-status/block/:position	Get a single block by chain position
POST	/audit/verify	Verify a specific event or a range of blocks

GET/audit/chain-status

Returns the overall health and integrity status of your organisation's hash chain, including the latest block, total event count, and any active integrity alerts.

bash

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

Response (chain valid)

json

{
  "valid": true,
  "organisationId": "org_xyz789",
  "totalEvents": 4822,
  "latestBlock": {
    "chainPosition": 4822,
    "blockHash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b",
    "timestamp": "2026-03-02T14:22:11.003Z"
  },
  "genesisBlock": {
    "chainPosition": 0,
    "blockHash": "sha256:e3b0c44298fc1c149afb4c8996fb924270000000",
    "timestamp": "2025-11-01T09:00:00.000Z"
  },
  "lastVerifiedAt": "2026-03-02T14:30:00.000Z",
  "verificationFrequencySeconds": 60,
  "integrityScore": 100,
  "alerts": []
}

Response (integrity failure)

If any block in the chain fails verification, valid is false and the alerts array contains details:

json

{
  "valid": false,
  "organisationId": "org_xyz789",
  "totalEvents": 4822,
  "integrityScore": 72,
  "alerts": [
    {
      "severity": "CRITICAL",
      "code": "HASH_MISMATCH",
      "message": "Block at chain position 3214 has a mismatched hash. Possible tampering detected.",
      "affectedRange": {
        "from": 3214,
        "to": 4822
      },
      "detectedAt": "2026-03-02T14:28:00.000Z"
    }
  ],
  "lastVerifiedAt": "2026-03-02T14:28:00.000Z"
}

GET/audit/chain-status/block/:position

Retrieve a single block by its integer chain position. The response includes both the stored hash and the freshly computed hash so you can independently verify integrity.

bash

curl "https://api.audital.ai/v1/audit/chain-status/block/4822" \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxx"

json

{
  "chainPosition": 4822,
  "blockHash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b",
  "previousHash": "sha256:7c4a8d09ca3762af61e59520943dc26494f8941b",
  "timestamp": "2026-03-02T14:22:11.003Z",
  "eventId": "evt_01HZABCDEF1234567890ABCD",
  "eventType": "CONFIG_CHANGE",
  "modelId": "mdl_abc123",
  "verified": true,
  "computedHash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b",
  "hashesMatch": true
}

POST/audit/verify(range mode)

Verify a contiguous range of blocks. Useful for periodic integrity checks of historical segments of 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 '{
    "rangeFrom": 4800,
    "rangeTo": 4822
  }'

json

{
  "valid": true,
  "rangeFrom": 4800,
  "rangeTo": 4822,
  "blocksVerified": 23,
  "verifiedAt": "2026-03-02T15:00:00.000Z",
  "rootHash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b",
  "summary": "All 23 blocks in range are cryptographically intact."
}

Integrating chain monitoring

For production deployments, we recommend polling /audit/chain-status from your own monitoring stack in addition to Audital's built-in checks. Audital also fires a chain.integrity_failure webhook event if it detects a breach. See the Webhooks page for details.

monitor_chain.py·python

import requests
import time

AUDITAL_API_KEY = "ak_live_xxxxxxxxxxxxxxxxxxxx"

def monitor_chain_integrity(poll_interval: int = 300):
    """Poll chain status every poll_interval seconds and alert on integrity failure."""
    while True:
        resp = requests.get(
            "https://api.audital.ai/v1/audit/chain-status",
            headers={"Authorization": f"Bearer {AUDITAL_API_KEY}"},
        )
        status = resp.json()

        if not status["valid"]:
            for alert in status.get("alerts", []):
                print(f"[CRITICAL] Chain integrity failure: {alert['message']}")
                print(f"  Affected blocks: {alert['affectedRange']['from']} - {alert['affectedRange']['to']}")
                # Trigger your alerting system here (PagerDuty, Slack, etc.)
                send_alert(alert)
        else:
            print(f"[OK] Chain valid. Latest block: {status['latestBlock']['chainPosition']}")

        time.sleep(poll_interval)

monitor_chain_integrity(poll_interval=60)

Status Codes

Status	Meaning
200	Verification completed (check valid field in response)
401	Invalid or missing API key
403	Insufficient scope — requires audit:read
404	Block position does not exist in this organisation's chain
429	Rate limit exceeded

Audit Events API →Core Concepts →Webhooks →