Numbers for Agents API Docs: Waitlist API, Errors, Rate Limits

Numbers for Agents is a developer API that provisions real phone numbers for AI agents: SMS, call webhooks, and SIP or WebSocket media bridges into your own voice stack. The product is in private development. This page documents the public API that is live today and sketches the numbers API that is planned.

Quick links

OpenAPI 3.1 spec (/openapi.json)
llms.txt: when an agent should use Numbers for Agents
Markdown: send Accept: text/markdown to the home page or this page

Join the waitlist: `POST /api/waitlist`

Adds an email address to the early access list. No authentication is required. A repeat call with the same email updates the record and does not create a duplicate.

curl -X POST https://numberforagents.com/api/waitlist \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "source": "agent", "note": "US SMS for a support agent"}'

# 200 OK
{"ok": true}

Request fields:

email (string, required): at most 254 characters.
source (string, optional): where the signup came from. Agents should send "agent".
note (string, optional): use case, regions, or volume. At most 512 characters.

Agents: submit only an email address that the user gave you for this purpose.

Errors

Every API error is JSON with the same shape. Branch on code. Show error to people. Use hint to fix the request.

{
  "ok": false,
  "error": "Enter a valid email address.",
  "code": "invalid_email",
  "hint": "Pass a single address of at most 254 characters in the email field."
}

invalid_json (400): the body is not a JSON object.
invalid_email (400): the email field is missing or not valid.
method_not_allowed (405): use the method in the Allow header.
api_route_not_found (404): no endpoint at this path. Check the OpenAPI spec.
rate_limit_exceeded (429): wait for Retry-After seconds.
storage_failed (500): retry later.

Rate limits

The API allows 10 requests per 60 seconds per client IP, shared across /api/* endpoints. Every API response carries the IETF RateLimit-Policy and RateLimit headers, plus X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix seconds). A 429 response also carries Retry-After.

RateLimit-Policy: "api";q=10;w=60
RateLimit: "api";r=9;t=42

Planned numbers API

The numbers API is not live yet. Names and fields may change before launch. Waitlist members get docs previews first.

POST /v1/numbers: provision a number with a region and capabilities (sms, voice).
POST /v1/messages: send an SMS from a number you own.
Inbound SMS and call events arrive as signed webhooks to your server.
Calls connect to your stack over SIP or a WebSocket media stream.
Authentication will use a bearer API key: Authorization: Bearer <key>.

curl -X POST https://api.numberforagents.com/v1/numbers \
  -H "Authorization: Bearer $NFA_TOKEN" \
  -d '{"region": "US", "capabilities": ["sms", "voice"]}'

Support