# Telnyx API sandbox

> A simulator of the Telnyx v2 API. Same paths, request bodies and response shapes as https://api.telnyx.com/v2, but nothing real happens: no message is delivered, no call is placed, no number is bought and nothing is billed.

## Summary

- **Base URL:** `https://api-sandbox.telnyx.com/v2` (production is `https://api.telnyx.com/v2`; swap the host, keep every path)
- **Auth:** your ordinary Telnyx API key as a Bearer token. There is no separate sandbox key and no signup.
- **No key needed:** `GET https://api-sandbox.telnyx.com/` returns a JSON description of the sandbox. This document is also available as JSON at https://telnyx.com/sandbox.
- **Isolation:** every organization gets its own sandbox, created on first use with seeded phone numbers and a test balance.
- **OpenAPI:** https://telnyx.com/.well-known/openapi.json (the same document describes the sandbox)
- **Site index:** https://telnyx.com/llms.txt

## Try it

```bash
# What the sandbox is. Needs no key.
curl https://api-sandbox.telnyx.com/

# The numbers your sandbox starts with
curl https://api-sandbox.telnyx.com/v2/phone_numbers \
  -H "Authorization: Bearer $TELNYX_API_KEY"

# Send a message from one of them. It is simulated, not delivered.
curl -X POST https://api-sandbox.telnyx.com/v2/messages \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"<a number from the list>","to":"+15550100123","text":"hello"}'
```

## Test controls

Operations under `https://api-sandbox.telnyx.com/v2/sandbox/` exist only in the sandbox:

- `GET /sandbox/clock`, `POST /sandbox/clock/freeze`, `/advance`, `/unfreeze`: read and move your sandbox's clock, so status changes and webhooks happen when you say.
- `POST /sandbox/simulate/inbound_message`, `/inbound_call`, `/call_event`: make an outside event happen.
- `GET /sandbox/webhooks/deliveries`: every webhook the sandbox sent you, with each attempt.
- `GET /sandbox/magic`: reserved numbers and text markers that force an outcome, such as a failed delivery.
- `POST /sandbox/reset`: back to the seeded state.

## Differences from production

- Nothing leaves the sandbox: no message is delivered, no call is placed, no number is bought and nothing is billed.
- State is kept in memory and can be cleared at any time.
- Responses follow the documented shapes of the public API; behaviour and timings are simulated and can differ from production.
- Webhooks are delivered to public addresses only, signed as production signs them.

## Moving to production

Switch the host from api-sandbox.telnyx.com to api.telnyx.com. Paths, bodies and the API key stay the same.
