Idempotency

Retry requests without calling anyone twice.

Networks fail. If your request to start a call times out, you cannot know whether the call was created. Send an Idempotency-Key header, and retrying becomes safe:

curl https://api.telleo.ai/v1/calls \
  -H "X-API-Key: $TELLEO_API_KEY" \
  -H "Idempotency-Key: lead-8812" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "17ea33d2-…", "phone_number": "[phone]"}'

Situation	Response
First request with this key	201 Created: the new call.
Same key, same body	200 OK: the same call as before, with "idempotent_replay": true. Nobody is called again.
Same key, different body	409 idempotency_key_reused, with the original call_id in details.

• Keys are up to 255 characters and are kept for your account indefinitely.
• Build them from your own ids (lead-8812, enquiry-5521-attempt-2) so that a retry naturally reuses the key, and a deliberate new attempt gets a new one.
• Two requests with the same key at the same moment create one call.

POST /v1/batches does not take an Idempotency-Key. Its rows are protected differently: a number that already has a waiting call is rejected as call_already_queued, so re-sending a batch does not queue its calls twice while they are still waiting.