API Reference — AIRMY REST API

Overview

Base URL: https://api.airmy.dev/v2

The AIRMY API is organised around REST. It accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Versioning: The current stable version is v2. We support the previous major version for 12 months after a new version ships. Breaking changes are announced in the changelog.

Quickstart

Canonical base URL: https://api.airmy.dev/v2

Demo API key (replace with a dashboard key for production): sk-airmy-demo-2026

Demo keys are for prototyping only: low rate limits, no SLA, and no access to private connectors. Replace with a dashboard-issued key before production. Session cookies from web login can authenticate browser-originated calls where supported.

Minimal invoke (create a run)

curl -X POST https://api.airmy.dev/v2/runs \
  -H "Authorization: Bearer sk-airmy-demo-2026" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"ag_01HXYZ","input":{"query":"Summarize Q1 revenue drivers"}}'

Platform capabilities

Bearer API keys and short-lived session tokens where enabled
Run records include tokens_used for transparency (calls remain the plan quota unit)
Streaming responses on supported endpoints (SSE) — see changelog per route
Guardrails and policy templates applied at the gateway tier
Idempotent run submission when client supplies an idempotency key (recommended)

The production edge may also expose additional service-specific routes; this reference documents the v2 product contract. Rust and Node gateways should be configured with the same Authorization: Bearer and session-cookie behaviour described under Authentication.

Authentication

Authenticate requests by including your API key in the Authorization header:

Authorization: Bearer sk-airmy-xxxxxxxxxxxxxxxxxxxx

AIRMY supports two token types:

API keys — Long-lived keys generated in the dashboard. Keep these secret. Do not commit them to source control.
Browser sessions — HttpOnly session cookies set by POST /api/auth/login. Use these for dashboard and web clients; cookies are sent automatically on same-site requests.

To rotate an API key: Dashboard → Settings → API Keys → Rotate. The old key remains valid for 24 hours after rotation.

Rate Limits

Rate limits are applied per API key on a per-minute basis:

Plan	Requests / min	Burst
Free	100	150
Developer	1,000	1,500
Business	10,000	15,000
Enterprise	Custom	Custom

When rate limited you'll receive a 429 Too Many Requests response. The Retry-After header indicates how many seconds to wait before retrying.

Agents

Method	Path	Description
GET	/agents	List all agents
GET	/agents/{id}	Get agent by ID
PATCH	/agents/{id}	Update agent configuration
DELETE	/agents/{id}	Archive agent

Deploy (hire catalog agents)

Method	Path	Description
POST	/agents/{catalog_key}/deploy	Hire a catalog agent into your org
POST	/agents/custom	Create a custom org agent

Runs

Method	Path	Description
POST	/runs	Invoke agent (create run)
POST	/runs/stream	Stream run output (SSE)
POST	/runs/{id}/action	Send action to an active run
GET	/runs/{id}	Get run result
GET	/runs	List runs with filters
DELETE	/runs/{id}	Cancel run

Usage, analytics & webhooks

Method	Path	Description
GET	/usage	Plan limits and monthly usage
GET	/analytics	Org analytics summary
GET	/api-keys	List scoped API keys
POST	/api-keys	Create scoped API key
GET	/webhooks	List webhook endpoints
POST	/webhooks	Register webhook endpoint

Request / Response Example

Invoking an agent and receiving a completed run result:

curl -X POST https://api.airmy.dev/v2/runs \
  -H "Authorization: Bearer sk-airmy-demo-2026" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"ag_01HXYZ","input":{"query":"Summarize Q1 revenue drivers"}}'

Response:

{
  "id": "run_01HXYZ123",
  "status": "completed",
  "output": { "result": "Q1 revenue was $4.2M, up 18% YoY..." },
  "latency_ms": 48,
  "tokens_used": 1247,
  "created_at": "2026-03-22T14:30:00Z"
}

Error Codes

Code	Name	Description
400	Bad Request	The request is malformed or missing required fields
401	Unauthorized	API key missing or invalid
403	Forbidden	Valid key but insufficient permissions for this resource
404	Not Found	Resource does not exist
422	Unprocessable Entity	Request understood but semantic validation failed
429	Rate Limited	Too many requests. Check `Retry-After` header
500	Internal Error	Something went wrong on our end. Reported automatically

SDKs

Official client libraries are available for Python, TypeScript/Node, and Go. See the SDK Libraries page for installation and quickstart guides.