API reference

Authentication

Access is org-scoped. Every request is authenticated as a specific workspace and carries that workspace’s permissions and credit balance — there is no account-wide key that can reach across tenants. In practice you authenticate with a short-lived, signed JWT (the same token model the app uses) or an org-scoped API key that you mint and can revoke.

• Send the token as a bearer header: Authorization: Bearer <token>.
• Requests are attributed to the workspace, so credit spend and audit trails stay accurate.
• Rotate and revoke keys from your workspace settings; treat them like passwords.

Send a message to an agent

The core interaction is sending Alex a message and reading the reply. A representative request looks like this:

POST /v1/agents/alex/messages
Authorization: Bearer <token>
Content-Type: application/json

{
  "message": "Summarize today's unread email and flag anything urgent.",
  "channel": "api"
}

A representative response:

200 OK
{
  "id": "msg_9f2c...",
  "agent": "alex",
  "status": "completed",
  "reply": "3 unread threads. 1 urgent: renewal from Acme ...",
  "credits_used": 4,
  "approvals": []
}

If the task involves a sensitive or outbound action, the response references a pending approval instead of completing. Your integration surfaces that approval to a human, who confirms the real recipient and message body before it proceeds — the same checkpoint the app uses.

{
  "id": "msg_9f2c...",
  "status": "awaiting_approval",
  "approvals": [
    {
      "id": "apr_71a0...",
      "action": "send_email",
      "to": "dana@acme.com",
      "subject": "Re: renewal",
      "body": "Hi Dana, ..."
    }
  ]
}

Errors

Errors use standard HTTP status codes. The ones worth handling:

• 401 Unauthorized — missing or expired token; refresh and retry.
• 402 Payment Required — the workspace is out of credits. Add a top-up or upgrade; see the billing guide.
• 403 Forbidden — the token’s role lacks permission for the action.
• 429 Too Many Requests — you hit a rate limit; back off and retry using the returned hint.

Rate limits

Requests are rate limited per workspace to keep the platform fair and stable. When you exceed a limit you receive a 429 with a retry hint; implement exponential backoff and treat rate limits as normal. Sustained high-volume needs are best handled on a custom Scale plan — talk to us about your throughput.

Getting access and help

To enable programmatic access and receive the versioned spec, reach out through the support guide. For deeper technical detail — events, the integration proxy, and environments — see the developer guide.