API Reference

All endpoints are under https://api.usetone.ai/v1. Authenticate with a tone_live_... API key.

Interactive docs available at https://api.usetone.ai/docs.

Numbers

POST /numbers/provision

Provision a new phone number.

Body

| Field | Type | Required | Description | |---|---|---|---| | callType | TRANSACTIONAL | PROMOTIONAL | Yes | TRANSACTIONAL uses 1600-series numbers. | | webhookUrl | string | No | URL to receive call events. |

Response — 201

{
  "id": "num_...",
  "phoneNumber": "+91...",
  "callType": "TRANSACTIONAL",
  "numberSeries": "1600",
  "webhookUrl": null,
  "createdAt": "..."
}

GET /numbers

List all numbers on this account.

Response — 200

{
  "numbers": [{ "id": "...", "phoneNumber": "+91...", ... }]
}

DELETE /numbers/:id

Release a number.

Calls

POST /calls/initiate

Initiate an outbound call.

Body

| Field | Type | Required | |---|---|---| | numberId | string | Yes | | to | string (E.164) | Yes | | callType | TRANSACTIONAL | PROMOTIONAL | Yes |

Response — 201

{
  "callId": "call_...",
  "state": "RINGING",
  "to": "+91...",
  "from": "+91..."
}

GET /calls

List calls with pagination.

Query params: page, limit (max 100), direction (inbound/outbound)

SMS

POST /sms/send

Send an SMS.

Body

| Field | Type | Required | |---|---|---| | to | string (E.164) | Yes | | from_number | string (E.164) | Yes | | message | string (max 1600) | Yes |

Rate limit: 10 messages per minute per API key.

GET /sms/logs

List SMS logs with pagination.

Query params: page, limit, direction, number

API Keys

POST /api-keys

Create a new API key.

GET /api-keys

List all API keys (prefixes only, secrets never returned).

DELETE /api-keys/:id

Revoke an API key.