List the organization’s agents
Every agent, live and draft. Small enough that it is not paginated.
Requires the read scope. A key with less gets 403 insufficient_scope.
Authorization: Bearer tone_live_… or tone_test_…. The prefix IS the environment: a test key reaches only the sandbox, and no request field bridges the two.
In: header
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/agents"{ "data": [ { "callSettings": { "background": { "sound": "none", "volume": 0.3 }, "hangupLine": { "text": "Thanks for your time. Goodbye." }, "maxCallSeconds": 600, "nudges": { "enabled": true, "hangupAfter": true, "steps": [ { "afterSeconds": 15, "line": { "text": null } } ] }, "openingLine": { "text": "Hi {{customer_name}}, I’m calling from Acme about your order." }, "voicemail": { "enabled": true, "windowSeconds": 30 } }, "createdAt": "2026-08-25T09:14:22Z", "evaluationCriteria": [ { "id": "confirmed_order", "name": "Confirmed the order", "prompt": "Did the customer explicitly confirm they still want the order?" } ], "id": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451", "inputVariables": [ { "default": "there", "description": "The customer’s first name, as it appears on the order.", "name": "customer_name" } ], "knowledgeBaseIds": [ "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451" ], "languages": [ "hi-IN", "en-IN" ], "llmProvider": "google", "name": "Order confirmation", "outputVariables": [ { "description": "Which day the customer agreed to take delivery. Leave empty if they did not commit to one.", "enumValues": [ "monday", "tuesday", "wednesday" ], "name": "delivery_day", "type": "enum" } ], "purpose": "promotional", "status": "draft", "sttLanguage": "auto", "sttMode": "transcribe", "sttModel": "saaras:v3", "sttProvider": "sarvam", "systemPrompt": "You call customers to confirm a cash-on-delivery order…", "tools": [ { "connectionId": "b4e6d8a1-9c3f-4b2e-8d7a-1f0e9c8b7a6d", "description": "Call this once the customer has agreed to a specific delivery date and time window.", "http": { "auth": { "header": "x-api-key", "in": "header", "name": "api_key", "secondary": { "in": "header", "name": "x-acme-secret", "secretId": "7c2b8e5d-1a3f-4e6b-8c9d-0e1f2a3b4c5d" }, "secretId": "3f1a7f6e-2b4c-4d1e-9a8b-5c6d7e8f9a0b", "type": "bearer" }, "bodyFormat": "json", "bodyRoot": "object", "headers": { "x-acme-source": "tone" }, "method": "POST", "timeoutMs": 5000, "url": "https://api.acme.example/v1/deliveries" }, "mock": { "enabled": true, "response": "{\"status\":\"booked\",\"slot\":\"2026-09-02T10:00:00+05:30\"}" }, "name": "book_delivery_slot", "parameters": [ { "description": "The agreed date as YYYY-MM-DD.", "name": "delivery_date", "required": true, "type": "string" } ], "preset": "cal.com/book", "speech": { "en-IN": "Let me check that for you.", "hi-IN": "मैं अभी देखता हूँ।" } } ], "ttsModel": "bulbul:v3", "ttsOptions": { "pace": 1 }, "ttsProvider": "sarvam", "ttsVoice": "simran", "updatedAt": "2026-08-25T09:14:22Z" } ]}Fetch a single agent
Returns the WORKING COPY — what an edit would change and what the next publish would freeze. To read what actually ran on a call, fetch that version by number instead.
Publish the working copy as a new live version
Freezes the current working copy into an immutable numbered version and points the agent at it. Publishing is what changes behaviour — editing does not. A running campaign finishes on the version it launched with; inbound calls always answer with the live version.