Chat (Ask Aira)

Natural language queries over your organization's notarized actions, agents, and compliance data.

All endpoints require a Bearer token. Base URL: https://api.airaproof.com/api/v1

Before using Ask Aira, an admin must set a default chat model in Settings → Models. Without a default model, requests without an explicit model parameter will return a 400 error.

Overview

Ask Aira lets you query your organization's data using natural language. It has full context of your notarized actions, registered agents, evidence packages, compliance snapshots, and usage data.

Each chat message counts as 1 operation against your plan limit. Self-hosted deployments have no limits.

Send Message

POST /api/v1/chat
Authorization: Bearer <token>

Request Body

Field	Type	Required	Description
`message`	string	Yes	Natural language question
`model_id`	string	No	Optional. Defaults to the organization's configured default model. If no default model is set and this parameter is omitted, the request will fail with a 400 error (`NO_DEFAULT_MODEL`).

Response (Streaming)

The response is streamed as Server-Sent Events (SSE):

data: {"type": "content", "text": "This week, your organization notarized"}
data: {"type": "content", "text": " 47 actions across 3 agents."}
data: {"type": "tool_use", "tool": "query_actions", "input": {"date_range": "7d"}}
data: {"type": "done", "usage": {"input_tokens": 1200, "output_tokens": 350}}

Non-Streaming Response

If the client does not accept text/event-stream, the full response is returned as JSON:

{
  "content": "This week, your organization notarized 47 actions across 3 agents...",
  "tools_used": ["query_actions"],
  "model": "claude-sonnet-4-6",
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 350
  },
  "request_id": "req_abc123"
}

Available Tools

Ask Aira can automatically query your data. The tools it uses include:

Tool	Description
`query_actions`	Search notarized actions by type, agent, date range
`query_agents`	Look up registered agents, versions, status
`query_cases`	Search case runs by model, decision, date
`query_usage`	Current month's usage, breakdown, overage
`query_evidence`	Search evidence packages
`query_compliance`	Search compliance snapshots by framework

Example Questions

"How many actions did lending-agent notarize this month?"
"Show me all DENY decisions from last week"
"What's our current usage against the plan limit?"
"Which agents have compliance snapshots for EU AI Act?"
"List all evidence packages created in Q1"

Model Selection

Organizations can configure their default chat model and allowed models in the dashboard under Settings > Models.

GET /api/v1/models/chat-default
PUT /api/v1/models/chat-default
GET /api/v1/models/chat-allowed
PUT /api/v1/models/chat-allowed

Set Default Chat Model

PUT /api/v1/models/chat-default
Authorization: Bearer <token>
Content-Type: application/json

Request Body

{
  "chat_default_model": "claude-sonnet-4-6"
}

Response

{
  "chat_default_model": "claude-sonnet-4-6",
  "request_id": "req_xyz456"
}

null or empty values for chat_default_model are rejected with a 400 error. To change the default, always provide a valid model identifier.

Set Allowed Chat Models

PUT /api/v1/models/chat-allowed
Authorization: Bearer <token>
Content-Type: application/json

Request Body — pass an array to restrict models, or null to allow all:

{
  "chat_allowed_models": ["claude-sonnet-4-6", "gpt-5.4"]
}

Or to allow all models:

{
  "chat_allowed_models": null
}

Response

{
  "chat_allowed_models": ["claude-sonnet-4-6", "gpt-5.4"],
  "request_id": "req_xyz789"
}

Python SDK

from aira import Aira

aira = Aira(api_key="aira_live_xxx")
response = aira.ask("How many email actions were notarized this week?")
print(response["content"])

On this page