> ## Documentation Index > Fetch the complete documentation index at: https://docs.miraiminds.co/llms.txt > Use this file to discover all available pages before exploring further. # Save a flow on an agent > Replaces the agent's graph without resending the rest of the agent. It also turns a single-prompt agent into a node-based one. The body is the graph: here, the one the test above fixed. Each save is a new agent revision, so you can roll it back. `if_revision` refuses the save if the agent changed since you read it; this collection keeps it up to date from the last agent response. Problems come back as `invalid_flow` with their paths, including node tools that are not on_call tools of this agent. The new graph applies from the next call. ## OpenAPI ````yaml /api-reference/openapi.json put /v2/agents/{agent_id}/flow openapi: 3.1.0 info: title: Mirai Voice API version: 2026-10-15.analysis-templates description: >- The v2 API for voice agents, calls, campaigns, phone numbers and speech. Every request carries `Authorization: Bearer sk_live_…`. Generated from the API's own contract and its Postman collection. servers: - url: https://sandbox.voice.miraiminds.co description: 'Sandbox: trial workspaces, before your company goes live' - url: https://prod.voice.miraiminds.co description: 'Production: workspaces that have gone live' security: - bearerAuth: [] tags: - name: Agents description: >- An agent is what a call runs: its prompt (or a node flow, see the Flows section), voice, language and limits. Write it once and dial it as often as you like; each call fills in its own `variables`. Every save creates a new revision. You can read old revisions, roll back to one, and publish a draft when it is ready. None of the requests here place a call or charge your wallet. - name: Calls description: >- Place a call, follow it while it runs, then read what happened: the transcript, the recording, the post-call analysis. `POST /v2/calls` answers before the phone rings, with an id. Everything after that is about that id. Live control and the live event stream work on browser calls (`channel: "web"`) and realtime sessions only; a phone call answers them with `400 unsupported_channel`. - name: Flows description: >- A node-based agent runs the call as a graph of steps. Each node has its own instructions, and the agent moves to the next node when a transition's condition is met, so a call with branches (wrong person, not now, reschedule) stays easy to follow and to change. The usual path: draft a graph from a brief or from recordings of your real calls, check it, test it with simulated calls, then save it on an agent. Drafting, transcribing and testing use AI models and charge your wallet; checking, saving and reading are free. Full guide: https://docs.miraiminds.co/v2/node-agents - name: Tools and secrets description: >- Connect your own APIs to an agent. A tool runs at one of three moments: * `pre_call`, before dialling: fetch context for the greeting, or skip the call. * `on_call`, when the agent decides to use it mid-conversation: look something up, book something. * `post_call`, after the call has settled: send the outcome to your CRM, schedule a call back. The order here is the order you'd use them in: see what's available, store your credential as a secret, add a tool, test it against your endpoint, then read each call's tool runs. Tools themselves cost nothing extra. Tool definitions use Mirai's own templates, like `{{ args.date }}` and `{{ secrets.crm_key }}`. A definition that doesn't validate comes back as a list, so you can fix everything at once: `{"error": "invalid_tools", "details": [{"path", "message"}]}`. Everything else uses the usual `{"error": {"code", "message"}}`. - name: Campaigns description: >- Call a whole list with one agent. Upload contacts, say which days and hours the campaign may ring, and start it. From then on it dials by itself: it paces itself, waits overnight, retries calls that didn't connect, skips numbers on your do-not-call list, and pauses itself when its budget or your wallet runs out. Campaign calls are ordinary calls. They show up in `GET /v2/calls`, send the same `call.*` webhooks and bill the same per-minute rate. In a sandbox workspace every campaign runs and bills at T5 (₹5 a minute), whatever tier you ask for. Money on a campaign is in **paise**: `"budget_paise": 50000` is ₹500. The requests run top to bottom: create saves `campaign_id`, and the rest use it. Starting a campaign rings every contact on it, so put numbers you're allowed to call in the bodies first. - name: Do-not-call list description: >- Numbers your campaigns will never dial. The list covers every campaign in the workspace, including ones that are already running: it's checked at the moment a contact is about to be called, so a number added mid-campaign is skipped from then on. A skipped contact stays in its campaign as `suppressed` and costs nothing. It doesn't apply to single calls placed with `POST /v2/calls`; check the list yourself before those if you need to. It's your own list, not the national DND register, and adding a number here doesn't meet your DND obligations. - name: Phone numbers description: >- The numbers your agents answer. Each one comes from the **Telephony** section: * **Rented from Mirai.** Once the rental is active, the number shows up here by itself (`ownership: managed`). * **From your own Plivo account.** Connect the account in Telephony, list its numbers, then bring one here with [Import a Plivo number](/api-reference/phone-numbers/import-a-plivo-number) (`ownership: customer`). Plivo keeps billing you for it. After that it's two steps, in this order: [Assign an agent](/api-reference/phone-numbers/assign-an-agent) (who answers), then [Turn on incoming calls](/api-reference/phone-numbers/turn-on-incoming-calls). `state` is `imported` until calls are on and `ready` after; `error` means the last attempt to turn calls on failed, and `setup_error` says why. Every change sends the number's current `version`, and each change raises it by one. If you're not sure what it is, read the number first; a stale version is a 409 `conflict` and changes nothing. To call out from one of your numbers, place a call with `phone_number_id` set to its id once it is `ready` (Indian destinations only). Calls on your numbers are billed like any other call. Every number also says how it is doing in `health`: `state` is `active`, `warming` (its first week, at half its pool's pace), `resting`, `cooling` (rested three times in a day; waits for you) or `retired`, with this hour's attempts and seven days of answers. You can rest, resume and retire your own numbers; a resting or retired number still answers calls to it. - name: Phone pools description: >- A pool is a group of your own phone numbers that a campaign, an agent or a single call can ring from. Each call takes the number best placed for it: a number a contact has already been rung from stays theirs on a retry, numbers in the contact's own circle come first, and the pool's pace (`max_per_hour`, per number) is held across every campaign and API call at once. A number whose answers drop well below its pool-mates' rests on its own for 45 minutes. Point a campaign at a pool with `pool_id` on [Create a campaign](/api-reference/campaigns/create-a-campaign), an agent with `calls_from: {"pool_id": …}`, or one call with `pool_id` on [Place a call](/api-reference/calls/place-a-call). `pool_id` and `phone_number_id` never go together. With nothing chosen, calls come from the agent's setting, then the pool marked `default_for_campaigns`, then the Mirai shared line. A call's `calls_from_source` is `pool` (with `pool_id`) when a pool picked its number. A single call on a pool whose numbers are all resting or at their pace this hour answers 409 `pool_busy` with `Retry-After`; one with no number that can call, 409 `pool_unavailable`. A campaign doesn't fail: it waits and carries on. `purpose` is what the calls are for: `outreach` (promotional), `reminders`, `support` or `other`. It sets the starting pace: 40 an hour for support, 60 otherwise. Pools are free; numbers are billed as numbers. - name: Telephony description: >- Getting a phone number for your agent. There are two ways, and a workspace can use both. **1. Rent a number from Mirai.** ₹500 a month, paid as ₹1,500 from your wallet every three months, renewing until you turn it off. Indian numbers need a business verification that Plivo approves once: read the requirements, submit your details and documents, then refresh until it's `accepted`. After that: search, quote, rent. The rented number appears in **Phone numbers** by itself. **2. Connect your own Plivo account.** Plivo keeps billing you directly. Connect it with your Auth ID and Auth Token, list the numbers it owns, and bring one over with [Import a Plivo number](/api-reference/phone-numbers/import-a-plivo-number). A Plivo main account can also rent new numbers through the same search → quote → rent requests, with its connection id as `account`. Either way you finish in **Phone numbers**: assign the agent that answers, then turn on incoming calls. The last two requests verify your own phone, so the workspace can ring it from Mirai's shared test number (test calls are placed from the Numbers page in the console). Indian (+91) numbers only for now. If phone numbers aren't available on the host you're calling, every request here answers 503 `telephony_unavailable`. - name: Transcriptions description: >- Turn a recorded call (or any recording) into a transcript with speakers and timestamps. Hindi, English, Gujarati and mixed speech are written the way they were spoken, never translated. ₹18 per hour of audio; failed and degraded jobs are free. - name: Speech to text description: >- Speech to text in ten languages, two ways: send one recording and get its text back in the same request ([Transcribe a recording](/api-reference/speech-to-text/transcribe-a-recording)), or stream live audio over one WebSocket per call and read partial transcripts while people speak, then one final transcript per utterance. Language codes: hi-IN, en-IN, gu-IN, mr-IN, pa-IN, bn-IN, ta-IN, te-IN, kn-IN or ml-IN. `wss://sandbox.voice.miraiminds.co/v1/audio/transcriptions/stream?language_code=hi-IN&encoding=mulaw&sample_rate=8000&endpointing=manual` (`wss://prod.voice.miraiminds.co` once your company has gone live), with the header `Authorization: Bearer sk_live_YOUR_API_KEY`. 8 or 16 kHz, 16-bit PCM, μ-law or A-law. A browser uses `?token=` from [Mint stream tokens](/api-reference/speech-to-text/mint-stream-tokens) instead, because it cannot set headers on a WebSocket. Send JSON text frames: `{"event": "speech_start"}`, then `{"event": "audio_input", "audio": ""}` as the audio arrives, then `{"event": "speech_end"}`; `{"event": "end"}` closes the session. You receive `session.begin` first, `transcript.partial` while an utterance is open, exactly one `transcript.final` per utterance, and `session.end` with `audio_seconds_billed` and `cost_paise`. Every event, both endpointing modes, limits and errors: https://docs.miraiminds.co/v2/stt-quickstart - name: Text to speech description: >- Turn text into speech in one request, and read back what each request cost. - name: Wallet description: >- Your prepaid balance and every line that moved it. Calls, text to speech, flow drafts, transcriptions and number rentals all debit the same wallet. - name: Reference description: The voice catalogue, and the API contract as a machine-readable document. paths: /v2/agents/{agent_id}/flow: put: tags: - Flows summary: Save a flow on an agent description: >- Replaces the agent's graph without resending the rest of the agent. It also turns a single-prompt agent into a node-based one. The body is the graph: here, the one the test above fixed. Each save is a new agent revision, so you can roll it back. `if_revision` refuses the save if the agent changed since you read it; this collection keeps it up to date from the last agent response. Problems come back as `invalid_flow` with their paths, including node tools that are not on_call tools of this agent. The new graph applies from the next call. operationId: put_agent_flow parameters: - name: agent_id in: path required: true description: The agent's id (`agt_…`). schema: type: string example: agt_01K2M4P7QRSTVWXYZ0A1B2C3 - name: if_revision in: query required: false description: Optional. The agent revision you read. schema: type: string example: '1' requestBody: required: true content: application/json: schema: additionalProperties: false description: >- A node graph: the conversation as nodes with their own instructions and transitions between them. See x-semantics.flow for the rules. properties: edges: items: $ref: '#/components/schemas/FlowEdge' maxItems: 40 minItems: 1 type: array nodes: items: $ref: '#/components/schemas/FlowNode' maxItems: 20 minItems: 2 type: array viewport: description: Editor camera. Any JSON; stored and returned as sent. required: - nodes - edges type: object x-max-bytes: 100000 examples: Save a flow on an agent: summary: Save a flow on an agent value: nodes: - id: persona type: globalNode data: name: Persona and rules prompt: >- You are Ashu, a service advisor at Mirai Motors. Speak everyday Hindi in Devanagari; common English words such as service, slot and workshop are fine. Say one or two short sentences, then listen. Never promise a discount, a price or a pickup. When the condition of one of your functions is met, call it at once without saying anything first. - id: identity type: startCall data: name: Confirm the customer greeting: >- नमस्ते, मैं मिराई मोटर्स से आशु बोल रहा हूं. क्या मेरी बात {{name}} जी से हो रही है? prompt: >- You have asked whether you are speaking with {{name}}. Wait for the answer. If they confirm, call confirmed_identity. If it is someone else or a wrong number, call wrong_person. Do not mention the car or the service before they confirm. - id: offer_slot type: agentNode data: name: Book the service prompt: >- Tell them their {{vehicle}} is due for service on {{due_date}}, and ask which day they can bring it to the workshop. When they name a day, read it back once and call slot_booked. If they are busy, ask once when to call them back, then call not_now. If they do not want to book at all, call not_now. extraction_enabled: true extraction_variables: - name: preferred_day type: string prompt: >- The day the customer chose for the service, in their words, for example Saturday or 20 August. - name: callback_time type: string prompt: >- When the customer asked to be called back, in their words. Empty if they did not ask. - id: goodbye type: endCall data: name: Close prompt: >- In one sentence, repeat what was agreed. Thank them and say goodbye. Do not ask anything else. allow_interrupt: false - id: not_customer type: endCall data: name: Wrong person prompt: >- Apologise for the trouble and say goodbye. Do not mention the car or the service. edges: - id: e1 source: identity target: offer_slot data: label: confirmed_identity condition: >- The caller confirmed they are the customer you asked for. - id: e2 source: identity target: not_customer data: label: wrong_person condition: >- The caller is someone else, or says it is a wrong number. - id: e3 source: offer_slot target: goodbye data: label: slot_booked condition: >- The customer named a day for the service and you read it back. - id: e4 source: offer_slot target: goodbye data: label: not_now condition: >- The customer does not want to book now, and you have asked once when to call back if they were busy. responses: '200': description: The agent, now node-based content: application/json: schema: $ref: '#/components/schemas/Agent' examples: The agent, now node-based: summary: 200 — the agent, now node-based value: revision: 5 draft: false archived: false analysis: enabled: false id: agt_01K2M4P7QRSTVWXYZ0A1B2C3 object: agent name: सर्विस रिमाइंडर system_prompt: >- आप आशु हैं, मिराई मोटर्स के सर्विस एडवाइज़र. {{name}} जी की {{vehicle}} की सर्विस {{due_date}} को ड्यू है. हिंदी में बात करें, छोटे वाक्य बोलें, और ग्राहक से सर्विस की तारीख कन्फर्म करें. first_message: >- नमस्ते, मैं आशु बोल रहा हूं मिराई मोटर्स से. एक मिनट है आपके पास? voice: voice_id: ashu language: hi language: hi max_duration_secs: 300 end_call: enabled: true message: धन्यवाद, आपका दिन शुभ हो. confirm: true voicemail: action: hangup background_sound: sound: 'off' behavior: interruptions: normal adaptive_interruptions: true secondary_languages: - en tools: [] flow: nodes: - id: persona type: globalNode data: name: Persona and rules prompt: >- You are Ashu, a service advisor at Mirai Motors. Speak everyday Hindi in Devanagari; common English words such as service, slot and workshop are fine. Say one or two short sentences, then listen. Never promise a discount, a price or a pickup. When the condition of one of your functions is met, call it at once without saying anything first. is_start: false allow_interrupt: true add_global_prompt: true extraction_enabled: false extraction_variables: [] - id: identity type: startCall data: name: Confirm the customer prompt: >- You have asked whether you are speaking with {{name}}. Wait for the answer. If they confirm, call confirmed_identity. If it is someone else or a wrong number, call wrong_person. Do not mention the car or the service before they confirm. greeting: >- नमस्ते, मैं मिराई मोटर्स से आशु बोल रहा हूं. क्या मेरी बात {{name}} जी से हो रही है? is_start: true allow_interrupt: true add_global_prompt: true extraction_enabled: false extraction_variables: [] - id: offer_slot type: agentNode data: name: Book the service prompt: >- Tell them their {{vehicle}} is due for service on {{due_date}}, and ask which day they can bring it to the workshop. When they name a day, read it back once and call slot_booked. If they are busy, ask once when to call them back, then call not_now. If they do not want to book at all, call not_now. is_start: false allow_interrupt: true add_global_prompt: true extraction_enabled: true extraction_variables: - name: preferred_day type: string prompt: >- The day the customer chose for the service, in their words, for example Saturday or 20 August. - name: callback_time type: string prompt: >- When the customer asked to be called back, in their words. Empty if they did not ask. - id: goodbye type: endCall data: name: Close prompt: >- In one sentence, repeat what was agreed. Thank them and say goodbye. Do not ask anything else. is_start: false allow_interrupt: false add_global_prompt: true extraction_enabled: false extraction_variables: [] - id: not_customer type: endCall data: name: Wrong person prompt: >- Apologise for the trouble and say goodbye. Do not mention the car or the service. is_start: false allow_interrupt: true add_global_prompt: true extraction_enabled: false extraction_variables: [] edges: - id: e1 source: identity target: offer_slot data: label: confirmed_identity condition: >- The caller confirmed they are the customer you asked for. - id: e2 source: identity target: not_customer data: label: wrong_person condition: >- The caller is someone else, or says it is a wrong number. - id: e3 source: offer_slot target: goodbye data: label: slot_booked condition: >- The customer named a day for the service and you read it back. - id: e4 source: offer_slot target: goodbye data: label: not_now condition: >- The customer does not want to book now, and you have asked once when to call back if they were busy. created_at: '2026-08-11T09:14:02Z' updated_at: '2026-08-11T09:56:02Z' '400': description: A node offers a tool the agent does not have content: application/json: examples: A node offers a tool the agent does not have: summary: 400 — a node offers a tool the agent does not have value: details: - path: flow.nodes[2].data.tools[0] message: >- node "offer_slot" offers tool "check_slots", which is not an on_call tool of this agent; add it with phase on_call or remove it from the node error: invalid_flow '409': description: The agent changed since you read it content: application/json: examples: The agent changed since you read it: summary: 409 — the agent changed since you read it value: error: code: conflict message: agent changed; read its current revision and retry components: schemas: FlowEdge: additionalProperties: false properties: animated: description: Editor field. Any JSON; stored and returned as sent. data: additionalProperties: false properties: condition: description: >- When to take it; given to the model as the function's description. Must not be blank. maxLength: 2000 minLength: 1 type: string label: description: >- The function name the model calls to take this transition. Unique among the source node's transitions. pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$ type: string required: - label - condition type: object id: description: Unique in the graph. minLength: 1 type: string source: description: A node id; not an endCall or the globalNode. type: string target: description: A node id; not the globalNode. type: string type: description: Editor field. Any JSON; stored and returned as sent. required: - id - source - target - data type: object FlowNode: additionalProperties: false properties: data: $ref: '#/components/schemas/FlowNodeData' id: description: Unique in the graph. pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$ type: string position: description: Editor layout. Any JSON; stored and returned as sent. type: description: >- startCall opens the call (exactly one); endCall ends it after its reply (at least one, no outgoing transitions); globalNode is a prompt prepended to every node with add_global_prompt (at most one, no transitions). enum: - startCall - agentNode - endCall - globalNode type: string required: - id - type - data type: object Agent: additionalProperties: false properties: analysis: description: >- Replace the whole analysis block. Omit output_schema to remove structured extraction. Requires enabled=true to run. oneOf: - type: 'null' - additionalProperties: false properties: enabled: default: false type: boolean output_schema: additionalProperties: false description: >- Root object schema from the documented bounded subset. Nested nodes use the same keywords; the server validates depth, node count and keyword/type compatibility. properties: additionalProperties: default: false type: boolean default: {} description: maxLength: 2000 type: string enum: maxItems: 100 type: array items: type: object maxItems: minimum: 0 type: integer maxLength: minimum: 0 type: integer maximum: type: number minItems: minimum: 0 type: integer minLength: minimum: 0 type: integer minimum: type: number properties: additionalProperties: description: Nested schema node; same supported subset. type: object maxProperties: 32 type: object required: items: type: string type: array uniqueItems: true type: const: object required: - type type: object prompt: maxLength: 2000 type: string success_criteria: maxLength: 2000 type: string templates: $ref: '#/components/schemas/AnalysisTemplates' type: object archived: default: false description: >- Archive to block new calls; false restores availability subject to draft validation. Accepted call snapshots remain unchanged. type: boolean background_sound: oneOf: - type: 'null' - enum: - 'off' - office type: string - additionalProperties: false properties: sound: default: 'off' enum: - 'off' - office type: string volume: maximum: 1 minimum: 0 type: number type: object behavior: additionalProperties: false description: >- How the agent takes turns with the caller. Always present; agents saved before this block existed read back with the defaults. properties: adaptive_interruptions: default: true description: >- The agent learns how loud the caller is from their own turns. A would-be interruption much quieter than the caller (someone else in the room) does not stop the agent and is not treated as the caller's words; if an interruption turns out to be nothing, the agent picks up the line it was cut off on. type: boolean interruptions: default: normal description: >- How easily the caller can cut the agent off while it speaks. easy: one word or about 0.5 s of speech; normal (the default, and the behaviour before this setting existed): two words or about 0.7 s; firm: three words or about 1.2 s; never: the agent always finishes its line, and what the caller said is answered right after. Acknowledgements (haan, ji, ok) never interrupt at any setting; a stop word (stop, ruko) interrupts at every setting except never. On a flow agent a node's own allow_interrupt false still applies; never makes every node non-interruptible. Trimmed and lower-cased; any other value, including an empty string, is 400. enum: - easy - normal - firm - never type: string required: - interruptions - adaptive_interruptions type: object calls_from: description: >- The phone number this agent's outbound calls ring from when the call or its campaign does not choose one; null when unset (the Mirai shared line). oneOf: - type: 'null' - additionalProperties: false properties: number: description: The number in E.164. type: string phone_number_id: type: string required: - phone_number_id - number type: object created_at: format: date-time type: string draft: default: false description: Drafts may have empty prompt or greeting, but cannot run calls. type: boolean emit_processed_webhook: default: true description: >- Send call.processed when this agent has post-call tools, analysis or a flow (a flow agent's event carries the call's flow outcome). Set false to turn the event off. type: boolean emit_queued_webhook: default: false type: boolean end_call: additionalProperties: false properties: confirm: default: true type: boolean enabled: default: true type: boolean message: default: Thanks, have a good day type: string type: object first_message: maxLength: 500 type: string flow: $ref: '#/components/schemas/Flow' description: Present only on a flow agent. id: type: string input_schema: anyOf: - additionalProperties: false description: >- Root object schema from the documented bounded subset. Nested nodes use the same keywords; the server validates depth, node count and keyword/type compatibility. properties: additionalProperties: default: false type: boolean default: {} description: maxLength: 2000 type: string enum: maxItems: 100 type: array items: type: object maxItems: minimum: 0 type: integer maxLength: minimum: 0 type: integer maximum: type: number minItems: minimum: 0 type: integer minLength: minimum: 0 type: integer minimum: type: number properties: additionalProperties: description: Nested schema node; same supported subset. type: object maxProperties: 32 type: object required: items: type: string type: array uniqueItems: true type: const: object required: - type type: object - type: 'null' description: >- Replace the entire input declaration. Null removes it and restores legacy string variables. language: minLength: 1 type: string max_duration_secs: default: 300 maximum: 1800 minimum: 30 type: integer name: minLength: 1 type: string object: const: agent revision: type: integer secondary_languages: description: >- Other languages callers may speak. Speech recognition listens for them as well as the primary language. Optional; the primary language is never repeated here. Always returned; [] when there are none. items: enum: - hi - en - gu - mr - bn - ta - te - kn - ml - pa - od type: string maxItems: 4 type: array system_prompt: maxLength: 12000 type: string tools: description: >- At most 40 tools: 10 pre_call, 20 on_call, 10 post_call. A PATCH replaces the whole list; null empties it. To edit one tool, use PUT/DELETE /v2/agents/{id}/tools/{name}. items: $ref: '#/components/schemas/Tool' maxItems: 40 type: array updated_at: format: date-time type: string voice: additionalProperties: false properties: language: type: string voice_id: type: string required: - voice_id type: object voicemail: additionalProperties: false properties: action: default: hangup enum: - hangup - message type: string message: type: string type: object required: - behavior - secondary_languages type: object FlowNodeData: additionalProperties: false properties: add_global_prompt: default: true type: boolean allow_interrupt: default: true type: boolean extraction_enabled: default: false type: boolean extraction_variables: default: [] items: $ref: '#/components/schemas/FlowVariable' maxItems: 12 type: array greeting: description: >- Exact line spoken on entering the node; the start node's greeting opens the call. maxLength: 1500 type: - string - 'null' is_start: description: Derived from type on save. type: boolean name: maxLength: 80 minLength: 1 type: string prompt: description: >- The node's instructions, including when to call each outgoing transition. {{variables}} are rendered per call. maxLength: 12000 minLength: 1 type: string tools: description: >- Names of this agent's on_call tools the node offers the model beside its transitions, in order. startCall and agentNode only; never end_call and never a transition label. Omitted when empty. items: pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$ type: string maxItems: 10 type: - array - 'null' uniqueItems: true required: - name - prompt type: object AnalysisTemplates: additionalProperties: false description: >- Pick the follow-up message after the call and fill in its variables. Exactly one of items or fetch. Requires analysis.enabled true. properties: fetch: additionalProperties: false description: >- Read the catalog from your endpoint after every call. Rendered like a post_call HTTP tool's request; secrets as {{ secrets.name }}. properties: body: description: >- JSON; POST only. Omitted on a POST: {"agent_id","call_id","metadata"}. headers: additionalProperties: type: string maxProperties: 20 type: object items_path: description: >- Dot path to the list, e.g. Data. Default: a top-level array, else the first array among templates, data, Data, items. maxLength: 256 type: string method: default: GET enum: - GET - POST type: string query: additionalProperties: type: string maxProperties: 20 type: object url: description: https only, port 443. maxLength: 2048 type: string required: - url type: object instructions: description: How to choose, in the business's words. maxLength: 2000 type: string items: items: $ref: '#/components/schemas/AnalysisTemplateItem' maxItems: 50 minItems: 1 type: array type: object Flow: additionalProperties: false description: >- A node graph: the conversation as nodes with their own instructions and transitions between them. See x-semantics.flow for the rules. properties: edges: items: $ref: '#/components/schemas/FlowEdge' maxItems: 40 minItems: 1 type: array nodes: items: $ref: '#/components/schemas/FlowNode' maxItems: 20 minItems: 2 type: array viewport: description: Editor camera. Any JSON; stored and returned as sent. required: - nodes - edges type: object x-max-bytes: 100000 Tool: additionalProperties: false description: >- One tool on the agent. The minimum is a name, a phase and an https url; every other field has a documented default, and a saved agent reads them back materialised. properties: builtin: description: >- builtin tools only: the settings for this builtin. See GET /v2/tools/catalog. type: object condition: description: null means always run. oneOf: - type: 'null' - $ref: '#/components/schemas/Condition' description: description: 'on_call only: what the model is told the tool does.' maxLength: 500 type: string enabled: default: true type: boolean execution: default: sync description: >- On-call HTTP tools may run in the background and return their result when ready. enum: - sync - async type: string kind: default: http description: >- Inferred when omitted: builtin for a catalogued builtin name with no request, http otherwise. enum: - http - builtin type: string name: description: >- Unique per agent. Becomes the tools. namespace and, for an on_call tool, the function name the model calls. pattern: ^[a-z][a-z0-9_]{1,39}$ type: string on_failure: default: continue description: abort is pre_call only and means do not dial. enum: - continue - abort type: string parameters: description: >- on_call only: JSON Schema for the model's arguments. Needs a tier whose model emits native tool calls (t3, t5); saving one on t1 returns 400 tool_style_unsupported. type: object phase: enum: - pre_call - on_call - post_call type: string request: additionalProperties: false description: >- http tools only. Every string is a {{ }} template over the phase's namespaces. properties: body: description: >- JSON template; a leaf that is exactly {{= path }} becomes the typed value. Not allowed on GET or DELETE. Omitted on an on_call POST/PUT/PATCH sends the model's arguments. headers: additionalProperties: type: string description: >- Host, Content-Length, Transfer-Encoding and Connection cannot be set. type: object method: default: GET enum: - GET - POST - PUT - PATCH - DELETE type: string query: additionalProperties: type: string description: Values are always URL-encoded. type: object url: description: >- https on port 443. Refused if it resolves to a private, loopback, link-local, CGNAT, multicast or metadata address, or to one of ours. maxLength: 2048 pattern: ^https:// type: string required: - url type: object response: additionalProperties: false properties: select: description: >- Keys promoted into variables as ., each at most 512 characters. items: type: string maxItems: 16 type: array strict: default: false description: 'true makes a non-JSON body a failure instead of {"text": …}.' type: boolean transform: description: >- jq, evaluated with a 100 ms budget and a 64 KB output cap. No input/inputs, no env, no modules. type: string type: object retry: additionalProperties: false description: >- Defaults 0 for pre_call and on_call, 2 for post_call. on_call may not retry: a second attempt is another whole timeout of silence for the caller. properties: attempts: minimum: 0 type: integer backoff_ms: default: 500 maximum: 10000 minimum: 0 type: integer type: object speak_while: description: >- on_call only: your own filler line, spoken while the tool runs. Empty means silence. maxLength: 300 type: string timeout_ms: description: >- Defaults and ceilings are per phase: pre_call 5000/15000, on_call 10000/30000, post_call 15000/60000. minimum: 100 type: integer when: description: 'on_call only: the WHEN rule appended to the system prompt.' maxLength: 1000 type: string required: - name - phase type: object FlowVariable: additionalProperties: false properties: name: description: Unique within the node. pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$ type: string prompt: maxLength: 2000 minLength: 1 type: string type: enum: - string - number - boolean type: string required: - name - type - prompt type: object AnalysisTemplateItem: additionalProperties: false properties: description: maxLength: 1000 type: string language: maxLength: 35 type: string name: description: Unique within the catalog. maxLength: 128 minLength: 1 type: string variables: description: Always returned; [] when the template takes none. items: additionalProperties: false properties: description: maxLength: 1000 type: string key: description: Unique within the template. maxLength: 128 minLength: 1 type: string required: - key type: object maxItems: 30 type: array required: - name type: object Condition: description: >- A condition gates a tool. Combinators all/any/not nest at most 8 deep; at most 64 comparisons. Fields are dotted paths into vars, call, now, tools, args (on_call) or analysis (post_call). secrets are not readable from a condition. A field that is missing at run time compares false. oneOf: - additionalProperties: false properties: all: items: $ref: '#/components/schemas/Condition' minItems: 1 type: array required: - all type: object - additionalProperties: false properties: any: items: $ref: '#/components/schemas/Condition' minItems: 1 type: array required: - any type: object - additionalProperties: false properties: not: $ref: '#/components/schemas/Condition' required: - not type: object - additionalProperties: false properties: field: description: >- Dotted path, e.g. vars.priority or tools.lookup.tier. Use .0 for the first item of a list. type: string op: enum: - contains - ends_with - eq - exists - gt - gte - in - is_false - is_true - lt - lte - matches - neq - not_contains - not_exists - not_in - starts_with type: string value: description: >- A string, number or boolean; an array for in/not_in. Omitted for exists/not_exists/is_true/is_false. required: - field - op type: object securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your workspace secret key, `sk_live_` followed by 32 hex characters. Create one in the console under **Developers**. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.