Cases

Submit Case

This is the most important endpoint. Everything else in Aira exists to support this.

POST /api/v1/cases
Authorization: Bearer aira_live_xxxxx

Request Body

Field	Type	Required	Description
`details`	string	Yes	The case details (1-50,000 chars)
`context`	object	No	Additional context (domain, jurisdiction, etc.)
`models`	string[]	Yes	Model IDs to use (2-10 models)
`options.human_review_threshold`	float	No	Disagreement threshold for human review (default: 0.4)
`options.store_details`	boolean	No	Store raw details encrypted (default: false, hash-only)
`options.idempotency_key`	string	No	Prevent duplicate execution on retry

Built-in Models

Model ID	Provider	Notes
`gpt-5.4`	OpenAI	Flagship, structured outputs
`gpt-5.2`	OpenAI	Proven stable
`gpt-5-mini`	OpenAI	Cost-optimized
`o3`	OpenAI	Reasoning-focused
`claude-opus-4-6`	Anthropic	Highest capability, 1M context
`claude-sonnet-4-6`	Anthropic	Best value, 1M context
`claude-haiku-4-5`	Anthropic	Fast, cost-effective
`gemini-3.1-pro`	Google	Latest Pro
`gemini-3.1-flash-lite`	Google	Fast, cost-effective

Cloud Provider Models

You can also use models through cloud providers by configuring adapters:

Provider	Configuration	Supported Models
AWS Bedrock	AWS credentials + region	Claude, Llama, Mistral
Azure OpenAI	Azure endpoint + deployment name	GPT-5.x series
Google Vertex AI	GCP project + region	Claude, Gemini

Self-Hosted Models

Model	Parameters	License
Llama 3.3 70B	70B	Llama Community License
Llama 4 Scout	17B active (MoE)	Llama Community License
Llama 4 Maverick	17B active (MoE)	Llama Community License
Mistral Large 3	41B active (MoE)	Apache 2.0
Qwen 3.5	397B (MoE)	Apache 2.0
DeepSeek V3.2	37B active (MoE)	MIT

Self-hosted models use constrained decoding (vLLM guided_json) for guaranteed schema compliance.

Example Request

curl -X POST https://api.airaproof.com/api/v1/cases \
  -H "Authorization: Bearer aira_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "details": "Should we approve this insurance claim for water damage, amount €12,500?",
    "context": {
      "domain": "insurance",
      "jurisdiction": "EU",
      "policy_type": "home",
      "claim_amount_eur": 12500
    },
    "models": ["gpt-5.4", "claude-sonnet-4-6", "gemini-3.1-pro"],
    "options": {
      "human_review_threshold": 0.3
    }
  }'

Response (201 Created)

{
  "case_id": "prn_01J8X...",
  "status": "complete",
  "consensus": {
    "decision": "APPROVE",
    "text": "2/3 models agree: APPROVE (gpt-5.4, claude-sonnet-4-6). Minority opinion: gemini-3.1-pro (REVIEW).",
    "confidence_score": 0.85,
    "disagreement_score": 0.28,
    "requires_human_review": false,
    "human_review_reason": null
  },
  "case_results": [
    {
      "model": "gpt-5.4",
      "model_version": "gpt-5.4-2026-02-27",
      "provider": "openai",
      "decision": "APPROVE",
      "confidence": 0.91,
      "key_factors": ["documented damage", "within policy limits", "valid coverage period"],
      "reasoning": "The claim is well-documented with photographic evidence...",
      "latency_ms": 1240
    },
    {
      "model": "claude-sonnet-4-6",
      "model_version": "claude-sonnet-4-6-20260115",
      "provider": "anthropic",
      "decision": "APPROVE",
      "confidence": 0.87,
      "key_factors": ["policy covers water damage", "amount within deductible limits"],
      "reasoning": "Based on the policy terms and documented damage...",
      "latency_ms": 980
    },
    {
      "model": "gemini-3.1-pro",
      "model_version": "gemini-3.1-pro-001",
      "provider": "google",
      "decision": "REVIEW",
      "confidence": 0.55,
      "key_factors": ["high claim amount", "needs adjuster verification"],
      "reasoning": "While the claim appears valid, the amount warrants...",
      "latency_ms": 750
    }
  ],
  "receipt": {
    "receipt_id": "rct_01J8X...",
    "payload_hash": "sha256:a1b2c3d4...",
    "signature": "ed25519:base64url...",
    "public_key_id": "aira-signing-key-v1",
    "timestamp": "2026-03-14T10:23:45.123Z",
    "timestamp_authority": "freetsa.org",
    "receipt_version": "1.0",
    "verify_url": "https://api.airaproof.com/api/v1/verify/rct_01J8X..."
  },
  "latency_ms": 1380,
  "created_at": "2026-03-14T10:23:45.123Z",
  "request_id": "req_01J8X..."
}

Response Fields

Field	Type	Description
`case_id`	string	Unique case run ID
`status`	string	`complete` or `failed`
`consensus.decision`	string	`APPROVE`, `DENY`, `REVIEW`, or `MIXED`
`consensus.confidence_score`	float	Weighted confidence (0.0-1.0)
`consensus.disagreement_score`	float	Model disagreement (0.0-1.0)
`consensus.requires_human_review`	boolean	True if disagreement exceeds threshold
`case_results[]`	array	Individual model responses
`receipt`	object	Cryptographic receipt

Human Review Triggered

When disagreement_score exceeds human_review_threshold, the response includes:

{
  "consensus": {
    "decision": "MIXED",
    "requires_human_review": true,
    "human_review_reason": "Disagreement score 0.72 exceeds threshold 0.30 — Article 14 human oversight triggered"
  }
}

Your application should route these decisions to a human reviewer before proceeding.

Error Isolation

If one model fails, the case still completes with the remaining models. The failed model appears in results with an error field:

{
  "model": "gemini-3.1-pro",
  "decision": "REVIEW",
  "confidence": 0.0,
  "key_factors": ["model_error"],
  "reasoning": "Model failed: TimeoutError",
  "error": "Request timed out after 30 seconds"
}

If ALL models fail, the API returns 503 MODEL_UNAVAILABLE.

Stream Case (SSE)

POST /api/v1/cases/stream
Authorization: Bearer aira_live_xxxxx

Same request body as POST /cases, but returns results as Server-Sent Events in real time. Each model's result is streamed as it completes, followed by consensus and receipt events.

Event Types

Event	Payload	Description
`started`	`case_id`, `models`, `request_id`	Case execution began
`model_complete`	`model`, `provider`, `decision`, `confidence`, `key_factors`, `reasoning`, `latency_ms`	A model finished
`consensus`	`decision`, `confidence_score`, `disagreement_score`, `requires_human_review`	Consensus computed
`receipt`	`receipt_id`, `payload_hash`, `signature`, `public_key_id`	Receipt created
`done`	`case_id`, `latency_ms`	Case complete
`error`	`message`, `case_id`	Error occurred

Example

curl -N -X POST https://api.airaproof.com/api/v1/cases/stream \
  -H "Authorization: Bearer aira_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "details": "Should we approve this claim?",
    "models": ["gpt-5.4", "claude-sonnet-4-6", "gemini-3.1-pro"]
  }'

SSE Response

event: started
data: {"case_id":"prn_01J8X...","models":["gpt-5.4","claude-sonnet-4-6","gemini-3.1-pro"]}

event: model_complete
data: {"model":"gemini-3.1-pro","provider":"google","decision":"APPROVE","confidence":0.88,"latency_ms":750}

event: model_complete
data: {"model":"claude-sonnet-4-6","provider":"anthropic","decision":"APPROVE","confidence":0.91,"latency_ms":980}

event: model_complete
data: {"model":"gpt-5.4","provider":"openai","decision":"APPROVE","confidence":0.93,"latency_ms":1240}

event: consensus
data: {"decision":"APPROVE","confidence_score":0.91,"disagreement_score":0.05,"requires_human_review":false}

event: receipt
data: {"receipt_id":"rct_01J8X...","payload_hash":"sha256:a1b2c3d4...","signature":"ed25519:base64url..."}

event: done
data: {"case_id":"prn_01J8X...","latency_ms":1380}

Streaming is ideal for real-time UIs where you want to show each model's result as it arrives, rather than waiting for all models to finish.

Get Case

GET /api/v1/cases/{case_id}
Authorization: Bearer aira_live_xxxxx

Returns the full case response (same shape as the execute response).

List Cases

GET /api/v1/cases?page=1&per_page=20
Authorization: Bearer aira_live_xxxxx

Returns a paginated list of case runs (lighter representation without full model responses).

On this page