API Reference

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.
• Session tokens — Short-lived tokens (1 hour TTL) obtained via POST /auth/token. Use these for frontend or mobile clients.

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:

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

Deployments

Runs

Pipelines (Orchestration)

Monitoring

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

SDKs

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