API Documentation

Everything you need to deploy and manage AI agents through the AIRouter API.

Base URL: https://airouter.us/api/v1
Agent endpoints use dedicated subdomains: https://{agent_id}-{provider}.airouter.us

Authentication

All requests require a Bearer token in the Authorization header. Obtain your API key by registering an account.

POST /api/v1/auth/register

curl -X POST https://airouter.us/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com"}'

# Response
{
  "user_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "api_key": "air_8a3b1f..."
}

Include the key in all subsequent requests:

Authorization: Bearer air_8a3b1f...

Quickstart

Create an agent and send your first request in two commands.

# Step 1 — Create an agent
curl -X POST https://airouter.us/api/v1/agents \
  -H "Authorization: Bearer $AIROUTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "summarizer",
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "system_prompt": "You summarize text concisely in bullet points.",
    "provider_api_key": "sk-ant-..."
  }'

# Step 2 — Send a request to your agent
curl https://a1b2c3d4-anthropic.airouter.us/v1/chat/completions \
  -H "Authorization: Bearer $AIROUTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Summarize the key points of quantum computing."}]
  }'

Create Agent

POST /api/v1/agents

Creates a new agent and returns a unique endpoint subdomain.

Parameter	Type	Description
name	string	Display name for the agent (e.g. "tweet-writer")
provider	string	One of: `anthropic`, `openai`, `xai`, `google`
model	string?	Model identifier. Defaults to provider's latest.
system_prompt	string?	System instructions baked into every request.
provider_api_key	string	Your API key for the chosen provider.
temperature	float?	Sampling temperature. Default `0.7`
max_tokens	int?	Max output tokens. Default `4096`

List Agents

GET /api/v1/agents

Returns all agents owned by the authenticated user.

curl https://airouter.us/api/v1/agents \
  -H "Authorization: Bearer $AIROUTER_KEY"

# Response
{
  "agents": [
    {
      "id": "a1b2c3d4",
      "name": "summarizer",
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514",
      "endpoint": "a1b2c3d4-anthropic.airouter.us",
      "total_requests": 142,
      "total_tokens": 58320
    }
  ]
}

Update Agent

PATCH /api/v1/agents/{agent_id}

Update agent configuration. Only provided fields are modified.

Delete Agent

DELETE /api/v1/agents/{agent_id}

Permanently deletes an agent and its endpoint. This action cannot be undone.

Chat Completions

POST https://{agent_id}-{provider}.airouter.us/v1/chat/completions

Send a chat completion request to your agent. The request format is OpenAI-compatible regardless of the underlying provider — AIRouter handles format conversion automatically.

Parameter	Type	Description
messages	array	Array of message objects with `role` and `content`
stream	bool?	Enable SSE streaming. Default `false`
temperature	float?	Override agent's default temperature.
max_tokens	int?	Override agent's default max tokens.

Note: The agent's system_prompt is automatically prepended to every request. You don't need to include it in messages.

Streaming

Set "stream": true to receive Server-Sent Events. The response format matches the OpenAI streaming spec — each chunk is prefixed with data: and the stream ends with data: [DONE].

curl https://a1b2c3d4-anthropic.airouter.us/v1/chat/completions \
  -H "Authorization: Bearer $AIROUTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello"}], "stream": true}'

data: {"choices":[{"delta":{"content":"Hi"},"index":0}]}
data: {"choices":[{"delta":{"content":" there"},"index":0}]}
data: {"choices":[{"delta":{"content":"!"},"index":0}]}
data: [DONE]

Supported Providers

Provider	Identifier	Default Model	Capabilities
Anthropic	`anthropic`	claude-sonnet-4-20250514	Chat, Streaming
OpenAI	`openai`	gpt-4.1	Chat, Streaming, Vision
xAI	`xai`	grok-3	Chat, Streaming
Google	`google`	gemini-2.5-pro	Chat, Streaming

Error Codes

Status	Meaning
`400`	Bad request — invalid parameters or unsupported provider
`401`	Unauthorized — missing or invalid API key
`404`	Agent not found or does not belong to your account
`409`	Conflict — email already registered
`429`	Rate limit exceeded
`502`	Provider returned an error — check your provider API key

Rate Limits

Default rate limits per account:

Tier	Requests/min	Agents
Free	30	3
Pro ($12/mo)	300	25
Business ($49/mo)	1,500	Unlimited

Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset.