REST API · v1

Zoetel API

The control plane at https://api.zoe-tel.com. Every path below is mounted in the tenant plane, /v1.

Authentication · Phone numbers

A request sends Authorization: Bearer with either a Supabase access token or an API key (zt_live_… or zt_test_…). The organisation is taken from that credential. It is never a path segment. When the caller belongs to more than one organisation, send X-Zoetel-Org with the organisation UUID.

curl https://api.zoe-tel.com/v1/me \
  -H "Authorization: Bearer $ZOETEL_API_KEY"

A successful body is { "data", "meta" }. Lists add page. A failure is { "error", "message", "request_id", "details", "retry_after_seconds" }. Branch on error. message can change. Every response, success or failure, carries X-Request-Id.

What a key can call

API keys reach two surfaces, numbers and voice. They cannot mint keys, manage the team, move money, or submit verification. Ordering a number (POST /v1/numbers/orders) and releasing one (POST /v1/numbers/{id}/release) are owner or admin actions. A key cannot call them.

What is not in this API

There is no /v2 and no https://api.zoetel.com. POST /v1/messages does not exist. GET /v1/messages is registered and answers unsupported.

/internal is the machine plane used by the voice network. It is not a customer API.