API foundations
Ship a production API integration.
Use schemas, scoped auth, idempotency, error handling, and rate-limit behavior before moving an agent workflow to production.
Token first
Make sure the agent has these scopes.
Create a new token or update the agent's current token before trying the calls below.
Required token scopes
email:send
billing:read
Outcome
What this gives you.
The integration can retry safely, fail clearly, and stay inside the authority granted to the agent.
Use when
The operational shape.
- You are turning a prototype workflow into production code.
- The integration creates messages, files, tasks, routes, or approvals that must not duplicate on retry.
- You need a builder or SDK to stay aligned with the live API contract.
API sequence
The calls to make.
01
Read the live schema
GET/v1/reference/api/
Generate types or validate a builder against the current API contract.
02
Create the right token
POST/v1/tokens/
Use session auth to grant only the scopes the integration needs for this workflow.
Default example
Use this as the default shape for this step.
{
"inbox_id": "inb_123",
"label": "production-workflow-worker",
"scopes": ["email:read", "email:send", "files:write", "workflows:write"],
"requires_approval": ["email:send"]
}
03
Send with idempotency
POST/v1/messages/
Attach an Idempotency-Key to every create or send call that may be retried.
Default example
Use this as the default shape for this step.
{
"reply_to_message_id": "msg_123",
"to": [{"email": "vendor@example.com"}],
"text_body": "Thanks. We received the invoice and will route it for review."
}
04
Handle API limits and errors
GET/v1/billing/usage/
Track usage, retry rate-limited calls, and surface structured errors to operators.
Controls
Review points.
- Idempotency belongs on side-effecting calls, especially sends, file writes, routes, and task creation.
- Treat schema and reference endpoints as builder inputs rather than copying enums into app code.
Related