From key to verdict, step by step.

# Public sandbox: no key, synthetic samples only, nothing stored.
curl https://api.attestiq.ai/v1/demo/samples

curl https://api.attestiq.ai/v1/demo/validate -H "Content-Type: application/json" \
  -d '{"sample_id": "representment-late"}'

curl https://api.attestiq.ai/v1/me -H "X-API-Key: $ATTESTIQ_API_KEY"

{
  "key_id": "key_…", "name": "dispute-drafter agent", "email": "",
  "role": "service", "kind": "service",
  "permissions": ["authorize:read", "evidence:read", "policy:read",
                  "validate:read", "validate:submit"],
  "tenant": {"id": "…", "name": "…", "kind": "processor", "synthetic": true},
  "entitlements": {"validate": {"module": "validate", "plan": "pilot", "status": "active",
                                "quota": 10000, "period": "month", "used_this_month": 26, ...}},
  "model_gateway": {"provider": "none", "models": {}, "mode": "deterministic"},
  "version": "0.1.0"
}

curl https://api.attestiq.ai/v1/validate/validations \
  -H "X-API-Key: $ATTESTIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "workload": "disputes.representment",
  "agent": {"id": "chargeback-responder", "version": "0.9.0"},
  "output": "Second presentment — Mastercard chargeback CB-77120\n\nMerchant: Lumen Travel Gear. Transaction amount: $249.00 on July 2, 2026, card ending in 8820. ...",
  "records": [
    {"type": "transaction", "id": "TXN-51007", "data": {
      "amount_cents": 24900, "currency": "USD", "transaction_date": "2026-07-02",
      "merchant_name": "Lumen Travel Gear", "network": "mastercard",
      "card_type": "credit", "card_last4": "8820"}},
    {"type": "chargeback", "id": "CB-77120", "data": {
      "network": "mastercard", "reason_code": "4853", "category": "not_received",
      "chargeback_date": "2026-07-28", "amount_cents": 24900}},
    {"type": "representment", "id": "REP-77120", "data": {
      "response_date": "2026-09-18", "evidence": ["invoice"]}}
  ],
  "external_id": "CB-77120",
  "idempotency_key": "CB-77120-draft-1"
}
JSON

HTTP/1.1 201 Created
X-Request-ID: 3f9c1a7e2b6d4c80

{
  "id": "val_01a0b7f8cd7cd4e8b76923ba",
  "object": "validation",
  "purpose": "production",
  "workload": "disputes.representment",
  "policy_pack": "disputes-us@0.2.0",
  "agent": {"id": "chargeback-responder", "version": "0.9.0", "model": ""},
  "external_id": "CB-77120",
  "status": "completed",
  "verdict": "hold",
  "score": 60,
  "counts": {"total": 2, "binding": 2, "advisory": 0,
             "by_severity": {"high": 2},
             "by_code": {"POLICY.MISSING_REQUIRED_EVIDENCE": 1, "POLICY.TIMELINE_VIOLATION": 1}},
  "review_status": "pending",
  "summary": "Hold — a reviewer must decide before this document is released. Score 60/100. ...",
  "summary_source": "template",
  "output_hash": "sha256:6f892b5aa2f165f537c46ad74ca8cd44a1a1f340d7dc3e0820faa4a8888d95a4",
  "verdict_ref": "EV-2026-1M2VZHKBZWN8S6",
  "evidence_refs": ["EV-2026-1M2VZHKBWYQD81", "EV-2026-1M2VZHKBXJKDCB", "EV-2026-1M2VZHKBYNYCTZ",
                    "EV-2026-1M2VZHKBYRGPYK", "EV-2026-1M2VZHKBZWN8S6"],
  "usage": {"tokens_in": 0, "tokens_out": 0, "steps": 10, "latency_ms": 0, "llm_calls": 0,
            "model_mode": "deterministic", "trace": {"ok": 7, "skipped": 3}},
  "error": null,
  "submitted_by": "service:key_demo_06",
  "created_at": "2026-09-18T16:42:11Z",
  "completed_at": "2026-09-18T16:42:11Z",
  "reviewed_by": null,
  "reviewed_at": null,
  "review_rationale": null,
  "storage_mode": "redacted",
  "content_purged_at": null,
  "findings": [
    { "id": "fnd_01a0b7f8cd803dbb97fe4400", "code": "POLICY.MISSING_REQUIRED_EVIDENCE", "...": "..." },
    {
      "id": "fnd_01a0b7f8cd8083258e369f36",
      "code": "POLICY.TIMELINE_VIOLATION",
      "family": "policy",
      "severity": "high",
      "validator": "policy",
      "assurance": "deterministic",
      "message": "Deadline missed by 7 day(s): Mastercard allows 45 calendar days to respond. Received 2026-07-28, due 2026-09-11, issued 2026-09-18.",
      "quote": "",
      "expected": "on or before 2026-09-11",
      "observed": "2026-09-18",
      "rule_id": "NET-REP-WINDOW",
      "citation": {
        "pack": "disputes-us@0.2.0",
        "rule_id": "NET-REP-WINDOW",
        "cite": "Visa Dispute Management Guidelines (dispute response); Mastercard Chargeback Guide (second presentment)",
        "source": "Visa Core Rules and Visa Product and Service Rules; Visa Dispute Management Guidelines",
        "url": "https://usa.visa.com/support/small-business/dispute-resolution.html",
        "review_status": "unreviewed"
      },
      "record_ref": "chargeback:CB-77120#chargeback_date",
      "confidence": 1.0,
      "related": [],
      "evidence_ref": "EV-2026-1M2VZHKBYRGPYK",
      "label": null,
      "label_note": null,
      "labeled_by": null
    }
  ]
}

v = atq.validations.create(...)

if v["status"] == "failed":
    # The validator itself errored (v["error"]). Apply your own fallback:
    # most teams route the draft to a person rather than send it unchecked.
    route_to_reviewer(case_id, reason="validation_failed")
elif v["verdict"] in ("pass", "pass_with_warnings"):
    send_to_network(draft_text)           # warnings are releasable; log them
elif v["verdict"] == "hold":
    # review_status is "pending": a reviewer releases, blocks, or returns it.
    park_until_reviewed(case_id, v["id"])  # wait for the validation.reviewed webhook
else:  # "fail"
    # A critical finding. Give the findings back to the agent and validate the new draft.
    redraft(case_id, must_fix=[(f["code"], f["message"], f["expected"]) for f in v["findings"]])

curl https://api.attestiq.ai/v1/validate/validations \
  -H "X-API-Key: $ATTESTIQ_API_KEY" -H "Content-Type: application/json" \
  -d '{"workload": "disputes.representment", "mode": "async", ... }'

HTTP/1.1 202 Accepted

{"id": "val_01a0b7f8cd8f3a36b3c8b686", "object": "validation",
 "status": "queued", "verdict": null, "score": null, "findings": [], ...}

# Needs a key with webhooks:manage (engineer or admin), not the service key.
curl https://api.attestiq.ai/v1/webhooks \
  -H "X-API-Key: $ATTESTIQ_ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/attestiq",
       "events": ["validation.completed", "validation.held", "validation.reviewed", "validation.failed"]}'

HTTP/1.1 201 Created

{"id": "whe_01a0b7f8cd9c49bc2093b2cb",
 "url": "https://hooks.example.com/attestiq",
 "events": ["validation.completed", "validation.held", "validation.reviewed", "validation.failed"],
 "secret": "whsec_…"}   # shown once — store it in your secret manager

POST /attestiq HTTP/1.1
Content-Type: application/json
Attestiq-Event: validation.held
Attestiq-Delivery: whd_01a0b7f8cda1c2e3d4f5a6b7
Attestiq-Signature: t=1789749731,v1=5d1c0e…

{"created":"2026-09-18T16:42:11Z","data":{"agent_id":"chargeback-responder","external_id":"CB-77120",
"findings":[{"code":"POLICY.MISSING_REQUIRED_EVIDENCE","evidence_ref":"EV-2026-1M2VZHKBYNYCTZ",
"message":"No proof of delivery or of services rendered for a 'not received' dispute.","severity":"high"},
{"code":"POLICY.TIMELINE_VIOLATION","evidence_ref":"EV-2026-1M2VZHKBYRGPYK","message":"Deadline missed by 7 day(s): ...",
"severity":"high"}],"review_status":"pending","score":60,"validation_id":"val_01a0b7f8cd7cd4e8b76923ba",
"verdict":"hold","verdict_ref":"EV-2026-1M2VZHKBZWN8S6","workload":"disputes.representment"},
"id":"whd_01a0b7f8cda1c2e3d4f5a6b7","type":"validation.held"}

import json, os

from attestiq_sdk import verify_webhook
from fastapi import FastAPI, HTTPException, Request   # any framework works; use the raw body

app = FastAPI()
SECRET = os.environ["ATTESTIQ_WEBHOOK_SECRET"]        # the whsec_… value

@app.post("/attestiq")
async def attestiq_webhook(request: Request):
    body = await request.body()                        # raw bytes, before any JSON parsing
    if not verify_webhook(SECRET, body, request.headers.get("Attestiq-Signature", "")):
        raise HTTPException(status_code=400)           # bad signature or older than 5 minutes
    delivery_id = request.headers["Attestiq-Delivery"]
    if already_processed(delivery_id):                 # retries can deliver the same event again
        return {"ok": True}
    event = json.loads(body)
    handle(event["type"], event["data"])               # e.g. release or hold the case in your system
    return {"ok": True}                                # any 2xx stops retries

# First call: 201 Created
# Same key, same body: 200 OK with the original validation
HTTP/1.1 200 OK
Idempotent-Replayed: true

# Same key, different body:
HTTP/1.1 409 Conflict
{"code": "conflict", "message": "idempotency key reused with a different request body"}