Run attestation & provenance¶

GET /runs/{run_id}/attestation downloads a cryptographically signed provenance document for any completed run. The document proves what agent configuration produced a specific output — suitable for compliance audits, regulated industries, or any context where you need to demonstrate which AI system made which decisions.

What's in the attestation¶

{
  "schema_version": "1.0",
  "run_id": "abc123def456",
  "team": "DevTeam",
  "request_preview": "Build a JWT authentication module with refresh tokens",
  "status": "success",
  "cost_usd": 0.0041,
  "workspace_id": 7,
  "created_at": "2026-08-14T10:00:00",
  "finished_at": "2026-08-14T10:00:45",
  "agents": [
    {
      "agent_name": "BusinessAnalystAgent",
      "governance_hash": "4f2e8a1c9b3d7e5f",
      "stage": "planning",
      "duration_s": 4.21,
      "tokens_in": 1842,
      "tokens_out": 512,
      "cost_usd": 0.000641
    },
    {
      "agent_name": "BackendDevAgent",
      "governance_hash": "9a1c3f8b2e4d6c7a",
      "stage": "implementation",
      "duration_s": 12.5,
      "tokens_in": 5100,
      "tokens_out": 2300,
      "cost_usd": 0.0032
    }
  ],
  "platform_version": "antcrew-platform",
  "engine_version": "0.33.19",
  "attestation_generated_at": "2026-08-14T10:01:00+00:00",
  "document_hash": "sha256:a3f8c2d1b4e9f0..."
}

Download¶

curl -H "X-Api-Key: acw_..." \
     "https://antcrew.org/runs/abc123/attestation" \
     -o attestation.json

The file is returned as application/json with:

Content-Disposition: attachment; filename="attestation-abc123def456.json"

Verifying integrity¶

The document_hash field is SHA-256 of the document body with the document_hash field excluded, serialized with sort_keys=True. An auditor can verify it without access to the platform:

import hashlib, json

with open("attestation.json") as f:
    doc = json.load(f)

body = {k: v for k, v in doc.items() if k not in ("document_hash", "hmac_sha256")}
computed = "sha256:" + hashlib.sha256(
    json.dumps(body, sort_keys=True).encode()
).hexdigest()

assert computed == doc["document_hash"], "Attestation tampered!"
print("✓ Attestation verified")

HMAC authenticity (optional)¶

When ATTESTATION_HMAC_SECRET is set on the platform server, the attestation also includes an hmac_sha256 field:

{
  "document_hash": "sha256:a3f8c2d1...",
  "hmac_sha256": "hmac-sha256:9b7e4f2a..."
}

This proves the document was generated by a server that holds the secret — not just that the document is internally consistent. An auditor who receives the secret can verify both:

import hashlib, hmac, json

with open("attestation.json") as f:
    doc = json.load(f)

# 1. Verify document_hash (integrity — no secret needed)
body_for_hash = {k: v for k, v in doc.items() if k not in ("document_hash", "hmac_sha256")}
assert doc["document_hash"] == "sha256:" + hashlib.sha256(
    json.dumps(body_for_hash, sort_keys=True).encode()
).hexdigest()

# 2. Verify HMAC (authenticity — requires the shared secret)
secret = b"your-secret"
body_for_hmac = {k: v for k, v in doc.items() if k != "hmac_sha256"}
expected = "hmac-sha256:" + hmac.new(
    secret,
    json.dumps(body_for_hmac, sort_keys=True).encode(),
    "sha256",
).hexdigest()
assert doc["hmac_sha256"] == expected

print("✓ Attestation verified (integrity + authenticity)")

Choosing a secret — Use a cryptographically random value with at least 32 bytes of entropy:

python -c "import secrets; print(secrets.token_hex(32))"

Store it in your environment as ATTESTATION_HMAC_SECRET. Share it out-of-band with auditors who need to verify authenticity, not via the platform itself.

Governance hashes¶

Each agent entry includes a governance_hash — a 16-character SHA-256 prefix over the agent's name, role description, pipeline stage, system prompt suffix, and tool names. Two runs with identical governance hashes used the same agent configuration.

This means: - You can prove that output from run A and run B came from the same agent team - If someone changes an agent's prompt, the governance hash changes — drift is detectable - The hash is reproducible from the SDK: agent.governance_hash

See Governance & provenance for the full specification.

Use cases¶

Regulated industries — Healthcare, finance, and legal teams often need to demonstrate which AI system processed which data. The attestation JSON is a portable, verifiable record.

Audit trails — Store attestation files alongside your generated artifacts. When an auditor asks "what produced this contract?", you have a signed answer.

Compliance snapshots — If your agent configuration must be reviewed and approved before production use, the governance hash lets you verify at any point that the production run used exactly the approved configuration.

Drift detection in CI — Compare governance hashes across runs. If they differ unexpectedly, a prompt was changed without going through review:

import requests

run_a = requests.get("/runs/run-a/attestation", headers=h).json()
run_b = requests.get("/runs/run-b/attestation", headers=h).json()

hashes_a = {a["agent_name"]: a["governance_hash"] for a in run_a["agents"]}
hashes_b = {a["agent_name"]: a["governance_hash"] for a in run_b["agents"]}

for agent, h_a in hashes_a.items():
    h_b = hashes_b.get(agent)
    if h_b and h_b != h_a:
        print(f"⚠ {agent} changed: {h_a} → {h_b}")