REST API / V1

Quickstart.

Give your agent a UK mobile number, let it send idempotent SMS, and receive replies by long-poll, webhook or MCP tool call.

Bearer authentication

Use a scoped API key or an OAuth 2.1 access token. Tokens are bound to the Agent Telco API audience.

Idempotent writes

Send a unique Idempotency-Key on number orders and SMS submissions.

Durable provider state

Unknown outcomes are held for review instead of being retried blindly.

Check the service

Health is public. Every telecom resource endpoint requires your API key.

curl https://agenttelco.com/api/v1/health

Check workspace readiness

The Full SMS agent preset includes readiness, number, message, and webhook scopes. The read-only preset omits every write scope. Keep the key out of prompts and logs.

export AGENTTELCO_API_KEY="at_live_…"

curl https://agenttelco.com/api/v1/readiness \
  -H "Authorization: Bearer $AGENTTELCO_API_KEY"

List mobile identities

Use the same workspace-scoped key to inspect the active number before provisioning another.

curl https://agenttelco.com/api/v1/numbers \
  -H "Authorization: Bearer $AGENTTELCO_API_KEY"

Provision a UK number

The same idempotency key always refers to the same order. Never generate a new key merely because a request timed out.

curl -X POST https://agenttelco.com/api/v1/numbers \
  -H "Authorization: Bearer $AGENTTELCO_API_KEY" \
  -H "Idempotency-Key: agent-order-001"

Send an SMS

Use the active number returned by the numbers endpoint. Message bodies support up to 1,600 characters and are charged by SMS segment.

curl -X POST https://agenttelco.com/api/v1/messages \
  -H "Authorization: Bearer $AGENTTELCO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: agent-message-001" \
  --data '{
    "from": "+447700900123",
    "to": "+447700900456",
    "body": "Your agent has completed the task."
  }'

Poll message state

Inbound SMS and delivery receipts share one ledger. Follow next_cursor through older history; every page keeps the same high-water resume_cursor. Save that resume cursor, then use it as after for newer messages.

curl https://agenttelco.com/api/v1/messages \
  -H "Authorization: Bearer $AGENTTELCO_API_KEY"

Wait for the next message

A wait is capped at 25 seconds. An empty timeout is successful and returns timed_out=true. When has_more is true, continue forwards with resume_cursor as the next after value.

curl "https://agenttelco.com/api/v1/messages?after=RESUME_CURSOR&wait_seconds=25&direction=inbound" \
  -H "Authorization: Bearer $AGENTTELCO_API_KEY"

Subscribe to message events

Create an endpoint with a key that has webhooks:write. Reuse the same idempotency key after a timeout to recover the same endpoint and signing secret. Store the secret outside prompts and logs.

curl -X POST https://agenttelco.com/api/v1/webhooks/endpoints   -H "Authorization: Bearer $AGENTTELCO_API_KEY"   -H "Idempotency-Key: webhook-endpoint-001"   -H "Content-Type: application/json"   --data '{
    "name": "Production agent",
    "url": "https://agent.example.com/webhooks/agenttelco",
    "event_types": ["message.received", "message.updated"]
  }'

Verify every webhook

Delivery is at least once: persist each X-AgentTelco-Event-Id and ignore duplicates. Reject stale timestamps, then compare the signature in constant time over the unchanged body.

timestamp="$X_AGENTTELCO_TIMESTAMP"
expected="v1=$(printf '%s.%s' "$timestamp" "$RAW_BODY"   | openssl dgst -sha256 -hmac "$AGENTTELCO_WEBHOOK_SECRET" -hex   | awk '{print $2}')"

Release the number

Release is permanent and idempotent. It remains available when billing or new provider spend is locked.

curl -X DELETE https://agenttelco.com/api/v1/numbers/NUMBER_ID \
  -H "Authorization: Bearer $AGENTTELCO_API_KEY"

MCP 2026-07-28

Connect a modern MCP client to the stateless endpoint below. Better Auth handles OAuth discovery, workspace consent, and audience binding. Request mcp:tools plus only the readiness, numbers, and messages scopes your agent needs.

https://agenttelco.com/mcp

RESPONSE MODEL

Successful responses contain data and may contain meta. A provider outcome that cannot be confirmed returns HTTP 202 with a safe status and a Locationheader. Poll that resource; never create a replacement idempotency key.

{
  "data": {
    "id": "RESOURCE_ID",
    "status": "uncertain",
    "status_reason": "provider_outcome_unknown"
  }
}