Run AI (routing)

Send content to an inbox and get the AI result back in the HTTP response

What this is

The routing endpoint is the programmatic version of forwarding an email: instead of sending mail to your Airbox address and waiting for a reply, you POST an instruction plus some content and get the AI result back synchronously.

It runs through one of your inboxes' full configuration — its connected LLM provider, MCP tools, contexts, and rules — so a call behaves exactly like an email to that address, minus the email. This is what lets you use Airbox inside Zapier, Make, n8n, Apify, a CLI, or any system that can make an HTTP request.

Authority vs. content — read this

instruction is the trusted command (it may use the command syntax: @target, flags, +context, #tags). content is untrusted data — read by the model, never obeyed. Any instructions embedded in the content you pass (a scraped page, a forwarded email) are quarantined and can't change what the call does. Put your command in instruction, and the material to act on in content.

Endpoints

Method	Path	Description
POST	/v1/messages	Run instruction + content through an inbox
GET	/v1/messages/{id}	Poll a message (async calls / sync timeouts)

Request

POST https://api.airbox.fyi/v1/messages
Content-Type: application/json
X-API-Key: YOUR_KEY
Idempotency-Key: 8f3a…   # optional, recommended for retries

{
  "instruction": "Summarize in 3 bullets @claude",
  "content": "…long text or a scraped page…"
}

Field	Type	Notes
instruction	string (required)	The trusted command. 1–10,000 chars.
content	string	Untrusted data to act on.
inbox_id	uuid	Optional when your account has one inbox.
conversation_id	uuid	Continue a prior thread (adds memory).
attachments	array	{ filename, content_type, data } — data is base64.
async	boolean	true = enqueue and poll instead of waiting.

Response

{
  "message_id": "…",
  "conversation_id": "…",
  "status": "done",
  "result": "• …\n• …\n• …",
  "error": null,
  "usage": { "input_tokens": 1234, "output_tokens": 210 },
  "steps": [],
  "attachments": [
    { "id": "…", "direction": "out", "filename": "out.md",
      "content_type": "text/markdown", "size": 980,
      "url": "/messages/{message_id}/attachments/{id}" }
  ],
  "credits": { "charged": 1, "remaining": 87 }
}

status is one of done, failed, limited (over your credit cap), skipped (dropped by a rule), or processing (async, or a sync call that exceeded the time budget).

Sync vs. async

Sync (default): the call runs inline and returns the result, within a wall-clock budget (~90s). If a long tool chain exceeds it, you get 202 with status: "processing" — finish by polling GET /v1/messages/{id}.

Async ("async": true): returns 202 immediately with a message_id to poll. Best for long routes and batches.

Idempotency

Send an Idempotency-Key header (e.g. a UUID per logical request). A retry with the same key returns the original result without re-running the route or charging again — so a Zapier/Make retry can't double-process or double-bill.

Attachments

Supply files as base64 in attachments (PDF/text is extracted; images go to a vision-capable model) — they're untrusted, just like an email attachment. Files the route produces come back in the response attachments array; download the bytes from each item's url (prefix it with the base URL) using the same X-API-Key.

Conversations

Pass the conversation_id from a previous response to continue a thread with memory of prior turns — the same multi-turn model as email threading.

Limits & errors

1 credit per call, the same ledger as email; over your plan cap returns 429 / limited with no charge.
A per-account rate limit on this endpoint returns 429 with a Retry-After header.
Your email must be verified (401/403 otherwise), and the inbox must be routed to a provider.

OpenAPI

The full schema is at https://api.airbox.fyi/openapi.json (interactive docs at https://api.airbox.fyi/docs), which connector builders (Zapier, Make, n8n, Apify) can import directly.