Aira

API Reference

Complete reference for all Aira API endpoints.

Base URL

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

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

Interactive Docs

Interactive API docs with a "Try it" button are available at:

Self-hosted deployments expose the same paths on your API domain.

Endpoints Overview

Authentication

MethodEndpointAuthDescription
POST/auth/registerNoneCreate organization + user account
POST/auth/loginNoneGet JWT token for dashboard
POST/auth/oauthNoneOAuth login (Google, GitHub, GitLab)
GET/auth/meJWTGet current user info
POST/auth/leave-orgJWTLeave organization (non-owners)
DELETE/auth/accountJWT (owner)Delete organization and all data

Team

MethodEndpointAuthDescription
GET/team/membersAdmin+List organization members
PUT/team/members/{id}/roleAdmin+Update member role
DELETE/team/members/{id}Admin+Remove member
GET/team/invitesAdmin+List pending invites
POST/team/invitesAdmin+Send invite
DELETE/team/invites/{id}Admin+Cancel invite
POST/team/transfer-ownershipOwnerTransfer org ownership to an admin

API Keys

MethodEndpointAuthDescription
POST/api-keysAdmin+Create new API key
GET/api-keysAdmin+List all keys (masked)
DELETE/api-keys/{id}Admin+Revoke a key

Cases (Core)

MethodEndpointAuthDescription
POST/casesRequiredExecute consensus case
POST/cases/streamRequiredSubmit case with SSE streaming
GET/cases/{id}RequiredGet case run details
GET/casesRequiredList case runs (paginated)

Receipts

MethodEndpointAuthDescription
GET/receipts/{id}RequiredGet receipt details
GET/receipts/{id}/exportRequiredExport as JSON

Verification (Public)

MethodEndpointAuthDescription
GET/verify/{receipt_uuid}NoneVerify receipt by ID
GET/verify/action/{action_uuid}NoneVerify action receipt
GET/.well-known/keysNoneList signing public keys

Actions (Agent Notary)

MethodEndpointAuthDescription
POST/actionsRequiredNotarize an agent action
GET/actionsRequiredList actions (paginated, filterable)
GET/actions/{id}RequiredGet action + receipt + authorizations
POST/actions/{id}/cosignJWT onlyHuman co-sign an action
POST/actions/{id}/holdRequiredSet legal hold
DELETE/actions/{id}/holdRequiredRelease legal hold
GET/actions/{id}/chainRequiredChain of custody

Agent Registry

MethodEndpointAuthDescription
POST/agentsRequiredRegister an agent
GET/agentsRequiredList agents (paginated)
GET/agents/{slug}RequiredGet agent detail + versions
PUT/agents/{slug}RequiredUpdate agent metadata
POST/agents/{slug}/versionsRequiredPublish new version
GET/agents/{slug}/versionsRequiredList versions
POST/agents/{slug}/decommissionRequiredDecommission agent
POST/agents/{slug}/transferRequiredTransfer ownership
GET/agents/{slug}/actionsRequiredActions by this agent
GET/agents/public/{slug}NonePublic identity page

Evidence & Discovery

MethodEndpointAuthDescription
POST/evidence/packagesRequiredCreate sealed evidence package
GET/evidence/packagesRequiredList evidence packages
GET/evidence/packages/{id}RequiredGet package detail
POST/evidence/time-travelRequiredPoint-in-time query
GET/evidence/liability-chain/{id}RequiredMulti-hop liability chain

Agent Estate

MethodEndpointAuthDescription
PUT/estate/agents/{slug}/willRequiredSet/update agent will
GET/estate/agents/{slug}/willRequiredGet agent will
POST/estate/agents/{slug}/death-certificateRequiredIssue death certificate
GET/estate/agents/{slug}/death-certificateRequiredGet death certificate
POST/estate/complianceRequiredCreate compliance snapshot
GET/estate/complianceRequiredList snapshots

Escrow

MethodEndpointAuthDescription
POST/escrow/accountsRequiredCreate escrow account
GET/escrow/accountsRequiredList accounts
GET/escrow/accounts/{id}RequiredGet account + transactions
POST/escrow/accounts/{id}/depositRequiredRecord liability commitment
POST/escrow/accounts/{id}/releaseRequiredRelease liability commitment
POST/escrow/accounts/{id}/disputeRequiredFile dispute

Provider Credentials

MethodEndpointAuthDescription
POST/provider-credentialsAdmin+Set/merge provider credentials
GET/provider-credentialsAdmin+Get credential status
DELETE/provider-credentials?provider=xxxAdmin+Delete provider credentials

Custom Models

MethodEndpointAuthDescription
POST/models/customRequiredRegister custom model
GET/models/customRequiredList custom models
GET/models/custom/{id}RequiredGet custom model
PUT/models/custom/{id}RequiredUpdate custom model
DELETE/models/custom/{id}RequiredDelete custom model
POST/models/custom/{id}/testRequiredTest model endpoint

Webhooks

MethodEndpointAuthDescription
POST/webhooksAdmin+Create webhook
GET/webhooksAdmin+List webhooks
DELETE/webhooks/{id}Admin+Delete webhook
GET/webhooks/{id}/deliveriesAdmin+List delivery log

Usage

MethodEndpointAuthDescription
GET/usageAdmin+Get usage summary
GET/usage/eventsAdmin+List usage events

Audit Logs

MethodEndpointAuthDescription
GET/audit-logsAdmin+List audit log events (filterable, paginated)

Policies

MethodEndpointAuthDescription
POST/policiesRequiredCreate policy
GET/policiesRequiredList policies
GET/policies/{id}RequiredGet policy detail
PATCH/policies/{id}RequiredUpdate policy
DELETE/policies/{id}RequiredDelete policy
POST/policies/{id}/activateRequiredActivate policy
POST/policies/{id}/deactivateRequiredDeactivate policy
POST/policies/{id}/dry-runRequiredTest policy on simulated action

Settlements

MethodEndpointAuthDescription
POST/settlementsAdmin+Seal new Merkle settlement
GET/settlementsRequiredList settlements
GET/settlements/{id}RequiredGet settlement detail
GET/settlements/{id}/receiptsRequiredList receipts in settlement
GET/settlements/inclusion-proof/{receipt_uuid}RequiredGet Merkle inclusion proof

Drift Detection

MethodEndpointAuthDescription
POST/agents/{id}/drift/baselineRequiredCompute baseline
POST/agents/{id}/drift/baseline/syntheticRequiredSeed synthetic baseline
POST/agents/{id}/drift/baseline/pooledRequiredPool baseline across cohort
GET/agents/{id}/driftRequiredGet drift status
POST/agents/{id}/drift/checkRequiredRun drift check (metered)
GET/agents/{id}/drift/alertsRequiredList drift alerts
POST/agents/{id}/drift/alerts/{alert_id}/acknowledgeJWTAcknowledge alert

Models & Preferences

MethodEndpointAuthDescription
GET/modelsOptionalList available models
GET/PUT/models/preferencesRequiredCases model preferences
GET/PUT/models/policy-preferencesRequiredPolicy model preferences
GET/PUT/models/sanitize-preferencesRequiredSanitize model preferences
GET/PUT/models/chat-defaultRequiredDefault chat model
GET/PUT/models/chat-allowedRequiredAllowed chat models

Sanitize

MethodEndpointAuthDescription
POST/sanitizeRequiredScan and process text
POST/sanitize/testRequiredDry-run (no audit)
POST/sanitize/detokenizeRequiredReverse tokenization
POST/sanitize/fileRequiredUpload file for sanitization
GET/sanitize/file/{token}/downloadNoneDownload sanitized file

Chat (Ask Aira)

MethodEndpointAuthDescription
POST/chatRequiredSend message (JSON or SSE)

Reputation

MethodEndpointAuthDescription
GET/agents/{slug}/reputationNoneGet reputation score
GET/agents/{slug}/reputation/historyRequiredGet score history
POST/agents/{slug}/reputation/attestRequiredSubmit attestation
GET/agents/{slug}/reputation/verifyNoneVerify score hash

Verifiable Credentials

MethodEndpointAuthDescription
GET/agents/{slug}/credentialNoneGet current credential
POST/credentials/verifyNoneVerify any VC
GET/agents/{slug}/credentialsRequiredCredential history
POST/agents/{slug}/credentials/revokeAdmin+Revoke credential

Notifications

MethodEndpointAuthDescription
GET/notifications/pendingRequiredGet pending notifications
POST/notifications/mark-readJWTMark notifications as read
POST/notifications/mark-all-readJWTMark all as read

Approvers

MethodEndpointAuthDescription
GET/approversAdmin+List approver emails
POST/approversAdmin+Add approver
DELETE/approvers/{email}Admin+Remove approver

SSO

MethodEndpointAuthDescription
GET/auth/sso/checkNoneCheck if SSO enabled for email
POST/sso/configureOwnerConfigure SAML
POST/sso/configure-oidcOwnerConfigure OIDC
POST/sso/enforceOwnerEnforce SSO-only login
GET/ssoOwnerGet SSO config
DELETE/ssoOwnerDelete SSO config

Billing

MethodEndpointAuthDescription
POST/billing/checkoutAdmin+Create Stripe checkout
POST/billing/portalAdmin+Open billing portal
GET/billing/statusAdmin+Get subscription status

Domains

MethodEndpointAuthDescription
POST/domainsAdmin+Add domain
POST/domains/{id}/verifyAdmin+Verify domain DNS
GET/domainsAdmin+List domains
DELETE/domains/{id}Admin+Remove domain

Endpoints

MethodEndpointAuthDescription
GET/endpoint-whitelistRequiredList whitelist
POST/endpoint-whitelistRequiredAdd to whitelist
POST/endpoint-whitelist/{id}/approveAdmin+Approve entry
DELETE/endpoint-whitelist/{id}Admin+Delete entry

Output Policies

MethodEndpointAuthDescription
GET/output-policiesRequiredGet output scan policy
PATCH/output-policiesRequiredUpdate output scan policy
POST/output-policies/testRequiredTest policy against sample

Gateway

MethodEndpointAuthDescription
POST/gateway/openai/v1/chat/completionsAPI KeyOpenAI-compatible proxy
POST/gateway/anthropic/v1/messagesAPI KeyAnthropic native proxy

Config

MethodEndpointAuthDescription
GET/configNoneGet deployment configuration

Health

MethodEndpointAuthDescription
GET/healthNoneService health check

Common Headers

Request

Authorization: Bearer aira_live_xxxxx
Content-Type: application/json

Response

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

Every response includes a request_id field for support and debugging.

Pagination

List endpoints return paginated results:

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

Query parameters:

  • page (default: 1, min: 1)
  • per_page (default: 20, min: 1, max: 100)

Idempotency

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.

Security

How Aira protects your data — encryption, access controls, infrastructure, and compliance.

Actions

Authorize agent actions before they run, then notarize the outcome after execution. The two-step flow is the core of Aira.

On this page

Base URLInteractive DocsEndpoints OverviewAuthenticationTeamAPI KeysCases (Core)ReceiptsVerification (Public)Actions (Agent Notary)Agent RegistryEvidence & DiscoveryAgent EstateEscrowProvider CredentialsCustom ModelsWebhooksUsageAudit LogsPoliciesSettlementsDrift DetectionModels & PreferencesSanitizeChat (Ask Aira)ReputationVerifiable CredentialsNotificationsApproversSSOBillingDomainsEndpointsOutput PoliciesGatewayConfigHealthCommon HeadersRequestResponsePaginationIdempotency