API Reference

Base URL

https://api.airaproof.com/api/v1

All endpoints are prefixed with /api/v1. Responses are JSON. All timestamps are ISO 8601 UTC.

The API also serves interactive documentation:

Method	Endpoint	Description
`POST`	`/auth/register`	Create organization + first API key
`POST`	`/auth/login`	Get JWT token for dashboard
`POST`	`/auth/oauth`	OAuth login (Google, GitHub, GitLab)

Method	Endpoint	Auth	Description
`POST`	`/api-keys`	Required	Create new API key
`GET`	`/api-keys`	Required	List all keys (masked)
`DELETE`	`/api-keys/{id}`	Required	Revoke a key

Method	Endpoint	Auth	Description
`POST`	`/cases`	Required	Execute consensus case
`POST`	`/cases/stream`	Required	Submit case with SSE streaming
`GET`	`/cases/{id}`	Required	Get case run details
`GET`	`/cases`	Required	List case runs (paginated)

Method	Endpoint	Auth	Description
`GET`	`/receipts/{id}`	Required	Get receipt details
`GET`	`/receipts/{id}/export`	Required	Export as JSON

Method	Endpoint	Auth	Description
`GET`	`/verify/{receipt_id}`	None	Verify receipt by ID
`GET`	`/.well-known/keys`	None	List signing public keys

Method	Endpoint	Auth	Description
`POST`	`/api-keys/{id}/byok`	Required	Set provider API keys
`GET`	`/api-keys/{id}/byok`	Required	Get BYOK status
`DELETE`	`/api-keys/{id}/byok`	Required	Revert to managed keys

Method	Endpoint	Auth	Description
`POST`	`/models/custom`	Required	Register custom model
`GET`	`/models/custom`	Required	List custom models
`GET`	`/models/custom/{id}`	Required	Get custom model
`PUT`	`/models/custom/{id}`	Required	Update custom model
`DELETE`	`/models/custom/{id}`	Required	Delete custom model
`POST`	`/models/custom/{id}/test`	Required	Test model endpoint

Method	Endpoint	Auth	Description
`POST`	`/webhooks`	Required	Create webhook
`GET`	`/webhooks`	Required	List webhooks
`DELETE`	`/webhooks/{id}`	Required	Delete webhook
`GET`	`/webhooks/{id}/deliveries`	Required	List delivery log

Method	Endpoint	Auth	Description
`GET`	`/usage`	Required	Get usage summary
`GET`	`/usage/events`	Required	List usage events

Method	Endpoint	Auth	Description
`GET`	`/models`	Optional	List available models (9 built-in + custom)
`GET`	`/models/preferences`	Required	Get disabled models list
`PUT`	`/models/preferences`	Required	Update disabled models list

Method	Endpoint	Auth	Description
`GET`	`/config`	None	Get deployment configuration

Method	Endpoint	Auth	Description
`GET`	`/health`	None	Service health check

Authorization: Bearer aira_live_xxxxx
Content-Type: application/json

Content-Type: application/json
X-Request-ID: req_a1b2c3d4e5f6

Every response includes a request_id field for support and debugging.

List endpoints return paginated results:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 245,
    "has_more": true
  },
  "request_id": "req_..."
}

Query parameters:

The case execution endpoint supports idempotency keys to prevent duplicate processing on network retries:

{
  "details": "...",
  "models": ["..."],
  "options": {
    "idempotency_key": "loan-app-12345-v1"
  }
}

If the same idempotency_key is sent twice, the second request returns 409 DUPLICATE_REQUEST with the original case ID.