AIR API Reference

The public natural-language gateway for structured data, capability discovery, and execution planning.

Authentication

Public AIR requests can use an API key or direct x402 payment. Browser users on the first-party site can also access the free path through the server-side proxy. Session tickets are not yet the primary documented path for /v1/air.

Authorization: Bearer air_platform_sk_...
Authorization: Payment <mpp-payment-header>
X-Payment: <mpp-payment-header>

Request Schema

{
  "query": "weather in Berlin",
  "cache_preference": "fresh"
}

query is required and must be 1-500 characters.

cache_preference is optional and supports "cached", "fresh", or "max-age=N".

Use Accept: text/event-stream to receive progressive SSE events instead of a single JSON response.

SSE Stream Format

When you request an event stream, AIR emits progressive planning and terminal events on the same endpoint.

event: intent
data: {"type":"intent","intent":"weather","task_kind":"lookup","confidence":0.96}

event: progress
data: {"type":"progress","step":"direct_api","message":"Checking known data"}

event: result
data: {"type":"result","result_kind":"weather","data":{...}}

event: done
data: {"type":"done"}

Response Schemas

AIR can return several top-level response families depending on whether it found direct data, execution work, or only capabilities.

{
  "success": true,
  "type": "result",
  "result_kind": "quote",
  "data": { ... },
  "freshness": { "cache_hit": true, "age_seconds": 4, "staleness_class": "fresh" },
  "provenance": { "provider": "CoinGecko", "provider_kind": "api", "confidence": 0.97 },
  "interpreted_request": { "intent": "crypto_quotes", "task_kind": "lookup" },
  "evidence_ledger": { "steps_executed": 1, "winning_step": "direct_api", "entries": [] }
}

type: "result" returns structured data like quotes, weather, headlines, pairs, gas, extract, or composition payloads.

type: "execution" returns an approval-aware async job when authenticated callers request an action.

type: "capabilities" returns related paid or trusted services when AIR finds relevant execution paths but not a direct answer.

type: "no_match" returns suggestions and optional related agents when AIR cannot satisfy the request.

Error responses use success: false with codes like invalid_query, invalid_api_key, rate_limited, or payment_failed.

Provenance & Trust

Every successful AIR result is designed to carry provenance, freshness, and execution evidence so clients can render trust and cost transparently.

freshness tells you whether the answer came from cache or live retrieval and how old it is.

provenance identifies the provider, provider kind, confidence, and canonical source URL when available.

evidence_ledger exposes the executed steps and winning source so downstream clients can display grounded UI.

Rate Limits & Pricing

AIR supports free/cache-backed usage for lightweight queries and premium access through API keys or x402. Anonymous callers are rate limited, and premium execution lanes are gated by caller policy.

View pricing and billing details →

Error Codes

Common HTTP responses include 400 invalid input, 401 invalid API key, 402 payment failure, 429 rate limit/budget exhaustion, and 500 internal errors.