> ## Documentation Index > Fetch the complete documentation index at: https://developers.mihu.ai/llms.txt > Use this file to discover all available pages before exploring further. # Add ONE guard rule (preserves existing rules) > Appends a guard rule. Existing guards are untouched. `when_condition` and `then_action` are required. If `then_action=forward`, also provide `destination_type` + `destination` (or `destination_agent_uuid` when destination_type=agent). If `then_action=end_conversation`, provide `say_before_end` for a polite closer. ## OpenAPI ````yaml https://app.mihu.ai/docs/api-docs.json post /api/v1/agents/{uuid}/guard-rules openapi: 3.0.0 info: title: Mihu API Documentation description: >- Welcome to Mihu API Documentation for developers.Here you can find all the information about the API endpoints and how to use them.If you have any questions or need help, please contact us at support@mihu.ai version: 1.0.0 servers: - url: https://{subdomain}.mihu.ai description: Your subdomain variables: subdomain: default: demo description: Subdomain name - url: /docs security: [] tags: - name: Agents description: >- Manage AI agents, settings, knowledge sections, rules, appointments, and channel provisioning - name: Contact Analyzers description: >- Configure what information should be extracted from conversations and how extracted values should update contacts, custom contact fields, or pipeline stages. Analyzer IDs use prefixes: `b_` means a built-in contact field, `f_` means a custom contact field, and `p_` means a pipeline stage rule. - name: Appointments description: Appointment management endpoints - name: Appointment Requests description: Appointment request endpoints - name: Assistant Channels description: >- Configure how a tenant user's Mihu Assistant is reached from outside the app — assign an inbox/WhatsApp number, set 'Your email'/'Your number', and optional PIN-based 2FA. This API is tenant-token authenticated but the resources it manages are per-user, so every request identifies the target user by their login email. - name: Availability Types description: Availability type endpoints - name: Builders description: >- Build and run apps on isolated cloud sandboxes (mihu Builders). Two ways in: **1. Describe it (Builder Agent):** POST /api/v1/builder-agents with a one-sentence prompt. The agent replies with questions (credentials, size, schedule); answer until it generates the code and deploys a running app with a public URL. **2. Ship your own code (Builders):** POST /api/v1/builders with your files + entrypoint. Returns a running app on a public HTTPS URL. --- **Which endpoint to call, by conversation `status` (the build-agent flow is async — always poll after a write):** | You have… | Call | Then | |---|---|---| | nothing yet | `POST /builder-agents` (prompt) | poll the conversation | | `status: processing` | nothing — it's working | keep polling `GET /builder-agents/{uuid}` (~2-3s) | | `status: gathering` (questions) | `POST /builder-agents/{uuid}/answers` | poll again | | `status: deployed` and want changes | `POST /builder-agents/{uuid}/rebuild` | poll again | | `status: deployed`, happy with it | operate it via `/api/v1/builders/{uuid}` (start/stop/logs/exec/files) | — | | `status: failed` | `POST /builder-agents/{uuid}/rebuild` with a fix, or start a new conversation | poll again | Rule of thumb: **write → then poll `GET /builder-agents/{uuid}` until status leaves `processing`.** Use `/answers` only while `gathering`; use `/rebuild` once `deployed`/`failed`. Once running, a builder exposes lifecycle controls (start/stop/auto-stop), live logs, a command terminal (exec), and direct file access. A preview URL only resolves while the builder is running. --- ### Connect via the standalone Builder MCP server Besides this REST API, the builder can be driven from your own AI client over the Model Context Protocol. The Builder MCP server lets a customer **build their own business integrations and apps** — CRMs, connectors, data migrations, webhooks, automation agents — by describing them in plain language from Claude Desktop, Claude Code, or Cursor. It is the integration and app builder for the customer, delivered over MCP. Each connection is bound to one tenant and scoped to it; no other tenant is reachable. **Get your connection details.** You get everything you need from the app: go to the **Builders** page and open the **Credentials** tab — the **Builder connection** panel there shows your three values. Server (for example https://builder.mihu.ai), Tenant (your workspace's builder tenant name), and Token (masked by default — click the eye icon there to reveal and copy it; it is your tenant key). Everything below comes from that panel. **Run the server (stdio).** Install with `pip install mcp`, then run it with your three values as environment variables: `MIHU_API_URL=Server MIHU_TENANT=Tenant MIHU_TENANT_KEY=Token python mcp_server.py`. **Register it with your MCP client.** In Claude Desktop's config, add an MCP server named mihu-builder whose command is `python`, whose argument is the path to `mcp_server.py`, and whose env sets MIHU_API_URL, MIHU_TENANT and MIHU_TENANT_KEY to your three values. In Claude Code, use `claude mcp add` with the same three env vars and the script path. **Tools the client gets:** create_agent, answer_agent, approve_agent, get_agent, list_agents, deploy_code, list_deployments, review_deployment, test_deployment, get_qa_report, get_logs, exec_command, start, stop, set_auto_stop, get_spending, store_credentials, and more. **Build flow (asynchronous — poll after each write):** create_agent, then poll get_agent; while gathering, call answer_agent and poll; when awaiting_approval, call approve_agent and poll; once deployed it is live with a preview URL. Keep your token secret — it authorizes everything for your tenant; rotate it from the Credentials tab if it leaks. - name: Call Actions description: >- Real-time control actions for an active call: say, forward, hangup, mute, and unmute. Each action targets a live call by its conversation UUID, returned as `conversation_uuid` from POST /api/v1/call. Requires a bearer token and a live (non-ended) call. - name: Campaigns description: Campaign management endpoints - name: Coaching Agents description: >- Coaching Agents turn evaluation results into coaching feedback for your agents — what went well, what to improve, and which resources to study. Each coaching agent is identified by its `uuid`. Quick start: 1. `POST /api/v1/coaching-agents` with a name — you get a ready-to-use coaching agent with sample templates and a training example. 2. Tune the style: `coaching_tone` (supportive, direct, constructive, motivational, or your own wording), `auto_trigger_threshold` (coach when the score drops below this %), and content options. 3. Make it the active coach with `POST /api/v1/coaching-agents/{uuid}/set-default`. Good to know: - One coaching agent is always the default; the first one you create becomes the default automatically. - Train the AI on your style with `training_examples` (an issue + your ideal coaching response) — 5-10 diverse examples work best. - Feedback is written in the `language` you set, e.g. "English". Recipe — recommend a resource when something is missing from the conversation: 1. Add the resource to `resource_library` with matching `topics`, e.g. `{"title": "Pricing Conversation Tutorial", "type": "video", "url": "https://example.com/pricing-video", "topics": "pricing, price objections, sales"}`. 2. Add the trigger rule to `general_guidelines`, e.g. "If the price was not mentioned during the conversation, point this out, explain why discussing price matters, and recommend the pricing video from the resource library.". 3. Keep `include_resources` on. The coaching feedback will now flag the gap and link the resource. - name: Contacts description: Contact management endpoints - name: Contact Approvals description: >- Manage AI-suggested contact field updates pending human review. Each approval is identified by its `uuid`. - name: Contact Fields description: >- Manage custom contact fields for your account. Each field is identified by its `key` (unique and immutable once created). - name: Contact Settings description: >- Toggle contact-list display preferences such as masking phone numbers or email addresses. Each setting is identified by its `key`. - name: Conversations description: Conversation management endpoints - name: Sessions description: Conversation session endpoints - name: Tables description: >- Tables are user-defined datasets that AI agents use as a knowledge base (semantic search over text) or as a real-time lookup (structured rows the agent queries during conversations). **When to create a table.** Create one whenever an agent needs to ground its answers in your data: product catalog, FAQ, pricing list, internal policies, customer records, business rules, etc. One table = one dataset on one topic. **How to create + populate.** Pick one of: - `POST /api/v1/data/tables` — create an empty table with a typed column schema (text/number/date/boolean/json/url). Use this when you have structured data and want to add rows yourself via the records endpoints. - `POST /api/v1/data/import/copypaste` — paste raw text. Best for FAQs, policy docs, or any unstructured knowledge content. - `POST /api/v1/data/import/file` — upload CSV/Excel/JSON/PDF/XML/audio. Best for spreadsheets, documents, transcripts. - `POST /api/v1/data/import/website` — crawl a URL. Best for public knowledge bases, marketing sites. **Records.** Once a table exists, add/update/delete rows via `POST|PUT|DELETE /api/v1/data/{uuid}/records[/{record}]`. Inspect the schema with `GET /api/v1/data/{uuid}/fields`. **Connecting to an agent.** Call `POST /api/v1/data/{uuid}/assign` to make a table available to an agent. After bulk changes, call `POST /api/v1/data/{uuid}/sync` to refresh the agent's index. **Lifecycle.** create → populate (records or import) → assign to agent → agent uses it at runtime → update/sync as data changes → delete when no longer needed. - name: Logs description: >- Read-only audit feeds covering three kinds of activity. **Actions** is a chronological stream of every task, workflow run, and AI action taken during a call — what your agents actually did, when, and how long it took. **API** records inbound requests made against this tenant's API (method, path, status, calling token, request/response bodies) — useful for debugging integrations and auditing access. **Webhooks** records outbound webhook deliveries sent to your registered endpoints (event, destination, status, payload, headers, response). Across all three, tokens, passwords, signatures and other secrets are masked before being returned. - name: Email Addresses description: >- Manage the mihu email addresses agents send and receive from. Create an address on the shared sending domain (instant) or connect your own domain (DNS or single-email verification), assign or unassign the handling agent, enable or disable an address, and check domain verification status. - name: Email Messages description: >- Send email through the mihu Connect channel: start a new email from one of your addresses, reply within an existing email conversation, or forward a conversation to a third party. Inbound email is received automatically and surfaced as conversations. - name: Evaluate description: >- Per-agent and global settings that control how conversations are sessionized and analyzed. WHAT EVALUATION DOES: At runtime, every conversation is grouped into 'sessions' (continuous bursts of messages). When a session ends — either because the customer goes idle for sessionization.timeout_minutes, or the conversation closes — the runtime fires SessionSummaryService and runs each enabled analyzer feature against the full session transcript. Outputs are persisted as 'evaluation' records. WHEN IT RUNS: - Voice calls and WhatsApp Call: at end of call (or after silence_timeout) - SMS, WhatsApp text, Instagram, FB Messenger: when the session creator job (SmsSessionCreatorJob / WhatsappSessionCreatorJob / equivalents) closes the session - Triggered automatically; not on demand WHICH CHANNEL'S CONFIG RUNS: - text.* features run for sessions on text channels (SMS, WhatsApp text, Instagram, FB Messenger, chat) - voice.* features run for sessions on voice channels (phone calls, WhatsApp Call) - Both blocks live on the same settings row; only the relevant one fires per session WHAT THE FEATURES PRODUCE: Each enabled feature emits a classification (one label per session, per feature) using its 'description' field as the LLM prompt. success_evaluation_prompt is special: it returns true/false based on the 'prompt' field — leave 'prompt' empty and the result is meaningless. summary_prompt is consumed by SessionSummaryService to produce the human-readable session summary in report_language. WHERE TO READ RESULTS: - GET /api/v1/sessions/{uuid}/evaluation — single session result - GET /api/v1/evaluations — list, filterable - GET /api/v1/analytics/evaluations — aggregated dashboard data COST CONSIDERATIONS: Each enabled feature is one extra LLM call per session. Disable features you don't read. is_active=false disables every analyzer for that agent (and skips the summary). WORKFLOW: 1. GET /default to see the workspace-wide config every agent inherits 2. POST /agents/{uuid}/evaluate/assign to give one agent its own override 3. PUT /agents/{uuid}/evaluate (or /default) for partial updates 4. DELETE /agents/{uuid}/evaluate to revert that agent to the default - name: Language description: Languages available for agent configuration. - name: Listings description: Listing management endpoints - name: Memorize description: >- Manage what your agents remember from contacts and conversations. There is one global default; each agent can optionally override it with its own settings. - name: Call description: Voice call endpoints - name: WhatsApp description: WhatsApp messaging endpoints - name: WhatsApp Calling description: WhatsApp voice call endpoints - name: SMS description: SMS messaging endpoints - name: Evaluations description: >- Evaluations are AI-generated analysis records for conversation sessions. Use these endpoints to list or retrieve scores, labels, reasons, and linked conversation/contact identifiers for quality review and reporting. - name: Schedules description: >- Schedules are bookable calendars used by agents and appointment flows. A schedule links to an availability type, stores assignment metadata, and can include custom questions for appointment collection. - name: Tasks description: >- Tasks are scheduled units of work for agents, such as outbound calls and WhatsApp template messages. Use task endpoints when you need to inspect campaign-generated work, create one-off outreach, queue a task, cancel it, or retry a failed attempt. - name: Transcriptions description: >- Transcriptions turn audio files or audio URLs into conversation text, session records, and optional AI evaluations. Use these endpoints to submit recorded calls, receive asynchronous completion webhooks, fetch transcription status, and retrieve the final transcript with analysis. - name: Analytics description: >- Aggregated analytics across calls, conversations, sessions, evaluations, intents, appointments, and messages - name: Flows description: >- Studio automation flows — list, create, read, update, delete. A flow is a trigger step + N action steps that fire on real events (e.g. inbound call → post to Slack → create CRM contact). Flows live in draft until POST /deploy makes them live. - name: Flow Steps description: >- Add / update / delete steps inside a flow. The first step is always a trigger; subsequent steps are actions. Step IDs and their ordering (`step_number`) are managed by the server — adding or deleting a step automatically renumbers and rewrites `{{stepN.field}}` references in downstream steps. - name: Flow Catalog description: >- Read-only discovery of integrations and their capabilities. Lists apps, triggers, actions, OAuth connections, agents, and dynamic field options. The MCP server uses this to translate natural language ("post to Slack #general") into the IDs/keys the action config requires. - name: Flow Executions description: >- Execution history for a deployed flow — every real trigger event that fires produces one execution row with per-step request/response/duration/status. - name: Voice IVR & Guards description: >- Two related but distinct features that decide when an agent transfers a call or ends a conversation. WHAT THEY ARE: - ROUTING RULES (Voice-Activated IVR): customer-intent-driven transfers. When the customer ASKS for something (sales, support, manager), routing rules pick the right destination. This is the IVR replacement. - GUARD RULES (Guard & Hand Over): situation-driven transfers or call-ends. When the runtime detects a sensitive SITUATION (legal complaint, profanity, compliance violation, customer in distress), the guard fires regardless of what the customer asked for. WHEN TO USE WHICH: - Customer says 'I want to speak to a manager' -> ROUTING rule (intent: customer wants escalation). - Customer threatens legal action -> GUARD rule (situation: compliance/safety overrides whatever the customer was asking). - Customer asks for technical support -> ROUTING rule. - Customer becomes abusive -> GUARD rule (then_action: end_conversation or forward). - Rule of thumb: routing = 'where do they want to go?', guard = 'this conversation needs to stop or hand off NOW'. PRIORITY AND ORDERING: - Routing rules have a numeric `priority` field. Lower number = higher priority = evaluated first. Ties resolved by insertion order. - Guard rules ALWAYS take precedence over routing rules. If a guard fires, routing is bypassed. - If multiple guards could fire on the same utterance, only the first match wins. DETECTION MECHANICS (routing only): - detection_mode = exact: the customer must say `trigger_keyword` literally. Fast, narrow, language-sensitive. - detection_mode = intent: the runtime AI uses `ai_prompt` + `phrases` to classify intent semantically. Broader, multilingual, requires good ai_prompt wording. - detection_mode = both: runs exact first, falls back to intent. Recommended for production. REQUIRED FIELDS FOR THE AI TO PICK THE RULE: - Routing intent/both: `ai_prompt` + `phrases` (3-5 examples). - Routing exact: `trigger_keyword`. - Guard: `when_condition` + `example_phrases`. Without these, the runtime cannot classify utterances and the rule never fires. CRUD MODES: - PUT /agents/{uuid}/routing-rules or /guard-rules — REPLACE all rules in one call. Old rules are deleted first. Use for bulk imports or full re-syncs. - POST /agents/{uuid}/routing-rules or /guard-rules — ADD one rule, leave others intact. Returns 201. Use for incremental builds. - PATCH /...{ruleUuid} — partial UPDATE of one rule. Only sent keys are touched. - DELETE /...{ruleUuid} — remove one rule. Per-rule POST/PATCH/DELETE preserve other rules; PUT replaces everything. - name: PBX Extension Connectors description: >- Voice PBX & Extension Connectors — register a PBX extension against an AI voice agent. This is the PBX-side configuration only; it does not provision a SIP trunk. Use it when you want to connect a number you've purchased from us into your existing PBX extension. If you already have a SIP trunk from a provider, use the SIP Trunking endpoints directly instead. - name: Phone Numbers description: Manage phone number inventory, channel bindings, search, and rates - name: Contact Pipeline description: >- Pipeline stages classify where a contact is in your sales, support, or onboarding process. Use these endpoints to define the ordered stage list, move contacts between stages through contact updates, and keep inactive stages out of normal selection while preserving history. - name: Pools description: >- Contact pools — named buckets of contacts that one or more campaigns draw from. A pool's `type` (FIFO / LIFO / Parallel) controls dispatch order when a campaign is running. **Typical workflow (build a pool from scratch):** 1. POST /api/v1/contacts — create the contacts you want to reach (or use existing UUIDs) 2. POST /api/v1/pools — create a pool 3. POST /api/v1/pools/{uuid}/contacts — bulk-add contacts by UUID 4. (attach to campaign — see Campaigns tag) **Inspect / manage:** - GET /api/v1/pools/{uuid}/contacts — paginated list of pool members with status, retries, started_at - DELETE /api/v1/pools/{uuid}/contacts/{contact_uuid} — remove one contact and cancel only THAT contact's pending tasks (not their tasks in other pools) - POST /api/v1/pools/{uuid}/duplicate — clone pool config, optionally with all members **Side effect on a running campaign:** if you POST /pools/{uuid}/contacts to a pool already attached to an In Process campaign, tasks are auto-created for the new contacts in EVERY running campaign attached to that pool. Same call works for draft campaigns too — it just doesn't create tasks until publish. **Delete guard:** DELETE /api/v1/pools/{uuid} returns 409 if the pool is attached to a campaign in In Process or Importing status. Stop or detach first. - name: QA Agents description: >- QA Agents score your conversations against a weighted skill scorecard and produce evaluation reports and coaching feedback. Each QA agent is identified by its `uuid`. Quick start: 1. `POST /api/v1/qa-agents` with a name — you get a ready-to-use scorecard (Greeting 15%, Empathy 20%, Compliance 25%, Resolution 25%, Sales 15%). 2. Adjust the scorecard with `PUT /api/v1/qa-agents/{uuid}/skills` — weights must always total 100%. 3. Make it the active evaluator with `POST /api/v1/qa-agents/{uuid}/set-default`. Good to know: - One QA agent is always the default; it evaluates sessions when no specific QA agent is chosen. The first one you create becomes the default automatically. - `evaluates_agent_type` controls who gets evaluated: `human` agents, `ai` agents, or `both`. - Reports are written in the `language` you set, e.g. "English". - name: Rules description: >- Campaign contact rules — call cadence, retry intervals, working-hours window, and escalation policy. A rule defines HOW often and WHEN a campaign reaches a contact; the campaign defines WHO and WHAT. **Typical workflow:** 1. POST /api/v1/rules — create a rule (call or text type) 2. POST /api/v1/campaigns — create a campaign in Draft status 3. PUT /api/v1/campaigns/{uuid}/rule — attach the rule (replaces any prior rule) 4. (continue with pool attachment + publish — see Campaigns tag) **Type-aware behavior:** - type='call' rules honor retry_interval_minutes and end_time (working-hours window). - type='text' rules force one-shot semantics: max_total_calls=1, retry/end_time nulled. Used for SMS and WhatsApp campaigns. **Caveat:** changing a rule on a campaign that's already In Process does NOT rebuild already-scheduled tasks. New tasks created after the change pick up new values; old ones keep the old cadence. To force a hard reset: stop campaign → assign new rule → publish again. - name: Simulations description: >- Simulation Studio — test an AI assistant against realistic AI customers before it goes live, and get a scored report with a full transcript per conversation. * * **What a simulation is.** One simulation = one assistant under test, on one channel, with a set of customer personas and test cases. A test case has a `title`, a `scenario` (what the simulated customer tries to do), an `expected` outcome, and `criteria` — short, objectively checkable statements the judge verifies from the transcript alone (e.g. 'Confirms date & time', 'Offers escalation', 'Keeps replies under 30 words'). Running the simulation executes `runs_per_case` conversations per test case; each conversation pairs one persona with the assistant, up to `max_turns` customer turns. * * **How faithful it is.** The assistant answers with its own production brain: its prompt, training rules, knowledge base, and its own configured model. With `with_intents=true` it also uses its real intent/appointment/guard tools — detected intents EXECUTE their events for real (webhooks and connected flows actually fire), so enable it deliberately. * * **Channels.** `voice`, `sms`, `whatsapp`, `whatsapp_call`, `email` (same set as Start Conversation). Text channels always run simulated (LLM ↔ LLM using the channel-appropriate prompt; nothing is sent externally, no real contacts touched). `voice` and `whatsapp_call` additionally support `call_mode=real`: the `caller_agent_uuid` agent's line (SIP trunk for voice, WhatsApp calling line for whatsapp_call — see `whatsapp_call_lines` in /options) places a REAL call to the assistant's number with its prompt fully overwritten by the persona — two live voice agents talk over real telephony, the assistant is exercised on its production inbound path, and the run carries a `record_url` recording. * * **State machine.** `draft → queued → running → passed | failed`. `passed` means the average judge score reached `pass_threshold`. A stopped simulation keeps results of finished conversations, or returns to `draft` if none finished. Stuck runs self-heal within minutes. * * **Billing.** Every assistant message in a simulated conversation is billed at the plan's text-message rate (see `message_rate` in /options; ceiling per run = test_cases × runs_per_case × max_turns × rate). Charges appear in the wallet transaction history as 'Simulation …'. An empty wallet blocks new runs. Real calls are billed as calls, not messages. * * **Which endpoint to call, by where you are:** * * | You have / want | Call | Then | * |---|---|---| * | nothing yet | `GET /simulations/options` | pick channel + assistant (+ caller line for real calls) | * | want AI-written config | `POST /simulations/generate-test-cases`, then optionally `/generate-personas` | edit the drafts, pass them into create | * | a config | `POST /simulations` (add `run:true` to start immediately) | poll | * | `state: queued/running` | `GET /simulations/{uuid}` (~3-5s) — run summaries update live; a run's transcript grows under `/runs/{runUuid}` | keep polling until `passed`/`failed` | * | want to abort | `POST /simulations/{uuid}/stop` | finished conversations keep their scores | * | `state: passed/failed` | `GET /simulations/{uuid}/report` | drill into `/runs/{runUuid}` for transcripts | * | want changes | `PUT /simulations/{uuid}` (409 while running), then `/run` again | previous spend stays in `billed_total` | * | a FAILED report, want auto-fix | `POST /simulations/{uuid}/optimize` | poll; then accept/reject the proposed field changes | * * **Self-improvement (optional).** On a finished report, `POST /{uuid}/optimize` proposes changes to the agent's STRUCTURED FIELDS (role, objective, tone, length, fallback response, company context) plus new Response Guidelines, Notes and Training Data — NOT a raw prompt. It returns a 'proposed' entry in `data.optimizations[]` with a plain-language `summary`, a `changes` object (`{fields:{col:newValue}, guidelines_add:[], notes_add:[], training_add:[]}`), and `before_score` — nothing is tested or applied yet. Then choose: `POST /{uuid}/optimize/accept {attempt_id}` to apply it, or `POST /{uuid}/optimize/trial {attempt_id}` to re-run the simulation with it first (poll `GET /{uuid}` — the attempt becomes 'ready' with `after_score`). Both accept and trial take an OPTIONAL `changes` body — pass an edited/trimmed version of the proposed `changes` to apply or test only what you want (drop a field key or a list item to skip it). Accept writes those fields to the agent, regenerates its prompt (via the same builder the Skills editor uses) and clears any custom_prompt override; `POST /{uuid}/optimize/revert` restores the changed fields. The live assistant is untouched until accept. * * **Attempt status lifecycle** (`data.optimizations[].status`): `proposed` → (`running` → `ready`, only if you trial it) → `accepted` | `rejected` | `reverted`. Only one attempt can be pending (`proposed`/`running`/`ready`) at a time; a second `optimize` returns 409 while one is pending. 409 reasons on these endpoints: no report yet, an attempt already pending, an empty change set, an empty wallet (trial), or (revert) the agent's prompt changed since it was applied. * * **Self-improvement worked example** (apply only some of the proposed changes): * 1. `POST /{uuid}/optimize` → `{ attempt_id }`. * 2. `GET /{uuid}` → find the `data.optimizations[]` entry with `status: proposed`; read its `changes`, e.g. `{ fields: { tone: Concise and factual, negative_response: … }, guidelines_add: [On SMS confirm the email by reading it back in full — never letter by letter], notes_add: [], training_add: [] }`. * 3. Drop anything you don't want — remove a key from `fields` or an item from a list. * 4. `POST /{uuid}/optimize/accept` with `{ attempt_id, changes: }` (omit `changes` to apply as-is). The agent's fields are written and its prompt rebuilt. * 5. Confirm on the agent with `GET /api/v1/agents/{agent_uuid}` (role/objective/tone/guidelines now reflect it). Undo with `POST /{uuid}/optimize/revert { attempt_id }`. * * **Reading a transcript.** Entries are `{who, text, at}` with `who` one of `customer` (the persona), `assistant` (the agent under test), or `tool` (a real intent/tool execution — carries `name`, `request`, `response`, `success`). A `tool` entry named `call_timeout` marks a call cut by its time budget. * * **Response envelope.** Every endpoint returns `{success: bool, message: string, data: ...}`; errors use HTTP status + `success:false` with the reason in `message`. A 409 on /run tells you exactly what to fix (already running, incomplete configuration, missing caller line, or empty wallet). * * **Operational rules (follow them — each prevents a misleading result):** * - If a test case's criteria reference the assistant's intents/activities (generate-test-cases often writes such criteria), run with `with_intents: true` — without it the assistant cannot trigger intents and those criteria fail unfairly. * - Size `max_turns` to the scenario: 3-4 turns suit a single-question smoke test; discovery/booking scenarios with multi-step criteria need 6-10 turns, or the judge will correctly fail criteria the conversation never had room to reach. * - `POST /simulations` with `run: true` can return 201 with 'created, but it could not start: …' in `message` — always check `data.state`: `queued` means running; `draft` means fix the stated reason, then call `/{uuid}/run`. * - A real-call run that errors with 'requested sip trunk does not exist' means that CALLER line's telephony is stale — pick a different `caller_agent_uuid` from /options and have the broken line re-provisioned. * - A real-call run that errors with 'produced no transcript' may still have connected (check `record_url` for a recording); it means the platform's transcripts never reached the run within 3 minutes. * - Judge scores vary between runs of the same configuration; for decisions use `runs_per_case: 3` (criteria resolve by majority) and treat single-run results as smoke signals only. * * **Minimal end-to-end example** (WhatsApp, auto-generated cases, run immediately): * 1. `GET /api/v1/simulations/options` → pick an agent whose `channels` contains `whatsapp`. * 2. `POST /api/v1/simulations/generate-test-cases` with body `{ agent_uuid: …, channel: whatsapp }` → returns cases. * 3. `POST /api/v1/simulations` with body `{ name: wa-smoke, channel: whatsapp, agent_uuid: …, test_cases: , runs_per_case: 1, run: true }`. * 4. Poll `GET /api/v1/simulations/{uuid}` every ~5s until `state` is `passed` or `failed`. * 5. `GET /api/v1/simulations/{uuid}/report` → score, criteria verdicts, issues, suggestions; transcripts under `/runs/{runUuid}`. - name: Contact Tags description: >- Manage contact tags for your account. Each tag is identified by its `uuid`. - name: WhatsApp Template Settings description: >- Template Settings make an APPROVED WhatsApp template campaign-ready by defining what fills each {{n}} placeholder when a message is sent to a contact. **Why two layers?** A WhatsApp template (see the WhatsApp Templates tag) is the Meta-approved message skeleton: 'Hi {{1}}, your {{2}} is ready'. A Template Setting is YOUR mapping for it: {{1}} = the contact's name, {{2}} = a fixed value like 'service appointment'. Campaigns reference a Template Setting, never a raw template — without one, a WhatsApp campaign has nothing to send. **Placeholder values — three kinds, resolved per contact at send time:** - `{{contact.}}` — a base contact field: name, surname, phone_number, email, country_code, timezone, primary_language - `{{custom.}}` — a custom contact field by its snake_case key (e.g. {{custom.car_model}}, {{custom.plate_number}}) - any other string — sent literally, identical for every contact If a mapped field is empty for a contact, the placeholder resolves to an empty string and the message still sends. **Typical workflow:** 1. GET /api/v1/whatsapp/templates?active_only=true — find an APPROVED template, note its uuid and how many {{n}} placeholders its content has 2. POST /api/v1/whatsapp/template-settings — create the mapping (one value per placeholder, keys '1'..'N') 3. POST /api/v1/listings with campaign_type='text' and contact_template_setting_uuid — launch the campaign **Deletion guard:** a setting referenced by a campaign that is In Process, Importing, Active, or Paused cannot be deleted (409). Finished campaigns don't block deletion. - name: Timezone description: Timezones available for agent configuration. - name: Voice Library description: >- Catalog of voices available to agents and the speed options each voice supports. - name: WhatsApp Templates description: >- Manage WhatsApp message templates — Meta-approved messages used for outbound WhatsApp campaigns. All endpoints are scoped to the tenant: you can only act on linked WABAs (WhatsApp Business Accounts). **Typical workflow — pull existing templates:** 1. GET /api/v1/whatsapp/wabas — discover WABAs linked to your tenant 2. POST /api/v1/whatsapp/templates/sync — pull all templates Meta has for a WABA (one-time bootstrap) 3. GET /api/v1/whatsapp/templates?waba_id=...&active_only=true — list APPROVED templates ready to use 4. Use a template UUID with POST /api/v1/whatsapp/template (one-shot send) or in a campaign **Typical workflow — create a brand-new template with a media header:** 1. POST /api/v1/whatsapp/templates/upload-media (multipart) — upload your image/video/document, receive a `handle` 2. POST /api/v1/whatsapp/templates — submit with `components` including HEADER referencing the handle 3. Wait — Meta approval is async, usually minutes. Status starts as PENDING. 4. POST /api/v1/whatsapp/templates/{uuid}/sync — refresh status until APPROVED, REJECTED, or PAUSED 5. Once APPROVED, use it in sends/campaigns **Component shape — quick reference:** - HEADER text: { type:'HEADER', format:'TEXT', text:'Hi {{1}}', example:{header_text:['John']} } - HEADER image: { type:'HEADER', format:'IMAGE', example:{header_handle:['']} } - HEADER video/document: same as image with format=VIDEO or DOCUMENT - BODY: { type:'BODY', text:'Order {{1}} ready', example:{body_text:[['12345']]} } note nested array - FOOTER: { type:'FOOTER', text:'Reply STOP to unsubscribe' } - BUTTONS group: { type:'BUTTONS', buttons:[ ... ] } with up to 10 buttons: QUICK_REPLY: { type:'QUICK_REPLY', text:'Yes please' } URL: { type:'URL', text:'Track', url:'https://example.com' } PHONE_NUMBER: { type:'PHONE_NUMBER', text:'Call', phone_number:'+1234567890' } COPY_CODE: { type:'COPY_CODE', example:'WELCOME10' } **Tenant scoping:** - 403: WABA is not linked to your tenant (no matching WhatsappSetting row) - 404 (not 403): templates that belong to other tenants — surfaced as 'not found' to avoid info leak. Same convention for non-whatsapp template types and orphan rows. **How auth works:** the existence of a WhatsappSetting row in the tenant DB IS the ownership proof — multi-tenant DB scoping handles isolation. The Meta access token used for API calls is the platform-global config('whatsapp.access_token'), the same token that powers every other WhatsApp send in this codebase (replies, campaigns, one-shot template sends). If WhatsappSetting.access_token is populated, that takes precedence — but onboarding doesn't fill it today, so the platform token is what actually runs. - name: Agent Channel Bindings description: Agent Channel Bindings - name: Agentic Search description: Agentic Search - name: Contact Blacklist description: Contact Blacklist - name: Flow description: Flow - name: SIP Trunk description: SIP Trunk paths: /api/v1/agents/{uuid}/guard-rules: post: tags: - Voice IVR & Guards summary: Add ONE guard rule (preserves existing rules) description: >- Appends a guard rule. Existing guards are untouched. `when_condition` and `then_action` are required. If `then_action=forward`, also provide `destination_type` + `destination` (or `destination_agent_uuid` when destination_type=agent). If `then_action=end_conversation`, provide `say_before_end` for a polite closer. operationId: a32b4a6df03ef663f19af306eaac0461 parameters: - name: uuid in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentGuardRuleInput' example: name: 'Compliance: PII over voice' when_condition: >- Customer asks the agent to read back full credit card or social security numbers over the call. example_phrases: - can you read my full card number - tell me my SSN then_action: forward selected_channels: - phone say_before_forwarding: For security, I will transfer you to a verified human agent. destination_type: extension destination: '210' is_active: true responses: '201': description: Guard rule added content: application/json: schema: properties: data: $ref: '#/components/schemas/AgentV1' type: object '404': description: Agent not found '422': description: Validation error (missing when_condition or then_action) security: - bearerAuth: [] components: schemas: AgentGuardRuleInput: description: >- Guard rules let the agent forward or end a conversation when a defined situation arises (compliance, safety, escalation). The runtime AI relies on `when_condition` and `example_phrases` to decide whether a customer utterance triggers the guard — rules without those fields filled cannot fire reliably. properties: uuid: type: string format: uuid readOnly: true nullable: true name: description: Optional short name for the guard rule. type: string example: Legal complaint escalation nullable: true when_condition: description: >- Required. Natural-language description of the situation that should trigger this guard. The runtime AI uses this as instructions when classifying customer utterances. Be specific — 'customer is angry' is too vague; 'customer uses profanity or threatens to escalate' is actionable. type: string example: >- Customer mentions a legal complaint, lawyer, lawsuit, or threatens to take legal action. example_phrases: description: >- Customer utterances that should trigger this guard. Provide 3-5 varied phrasings — the runtime AI uses these as positive examples when classifying. type: array items: type: string example: I'm calling my lawyer about this then_action: description: >- What the runtime agent does when the guard fires. `forward` transfers to a human or another agent; `end_conversation` politely ends the call/chat. type: string enum: - forward - end_conversation example: forward selected_channels: description: Channels where this guard is active. Defaults to phone-only. type: array items: type: string enum: - phone - instagram - whatsapp - facebook_messenger say_before_forwarding: description: Message spoken before the transfer when then_action=forward. type: string example: >- I understand this is important — let me connect you with someone who can help. nullable: true say_before_end: description: Message spoken before ending when then_action=end_conversation. type: string example: >- I'm sorry I couldn't help further. Please contact our team directly. Goodbye. nullable: true destination_type: description: >- Where the call is sent when then_action=forward (same semantics as routing rules). type: string enum: - extension - phone - agent nullable: true destination: description: >- Destination value (extension, SIP URI, or E.164 phone) when then_action=forward. type: string nullable: true destination_agent_uuid: description: Target agent UUID when destination_type=agent. type: string format: uuid nullable: true is_active: type: boolean example: true is_default: description: >- Marks this guard as a default that auto-applies to new agents in the workspace. type: boolean example: false type: object AgentV1: properties: agent_uuid: type: string format: uuid name: type: string description: type: string nullable: true company_name: type: string nullable: true role: type: string nullable: true objective: type: string nullable: true tone: type: string nullable: true behavior_guidelines: type: string nullable: true company_service: type: string nullable: true topic: type: string nullable: true length_detail: type: string nullable: true interest_of_product: type: string nullable: true negative_response: type: string nullable: true status: type: string enum: - pending - ready - in_progress - paused - completed custom_prompt: type: string nullable: true language: type: string speed: type: string timezone: type: string appointment_scheduling_enabled: type: boolean appointment_scheduling_randomly: type: boolean custom_llm_url: type: string nullable: true recommendations: description: >- JSON string of channel recommendations populated asynchronously after creation type: string nullable: true settings: properties: voice: type: object text: type: object memorize: type: object evaluation: type: object type: object guidelines: type: array items: $ref: '#/components/schemas/AgentGuidelineInput' notes: type: array items: $ref: '#/components/schemas/AgentNoteInput' procedures: type: array items: $ref: '#/components/schemas/AgentProcedureInput' training: type: array items: $ref: '#/components/schemas/AgentTrainingInput' intents: type: array items: $ref: '#/components/schemas/IntentV1' webhooks: description: Agent-scoped webhooks, capped at 5 per agent type: array items: $ref: '#/components/schemas/AgentWebhookV1' appointments: type: object routing_rules: type: array items: $ref: '#/components/schemas/AgentRoutingRuleInput' guard_rules: type: array items: $ref: '#/components/schemas/AgentGuardRuleInput' phone_numbers: type: array items: properties: phone_number_uuid: type: string format: uuid nullable: true number: type: string status: type: string enum: - active - pending - inactive - deleted nullable: true country_code: type: string nullable: true type: type: string nullable: true capabilities: properties: call: type: boolean nullable: true sms: type: boolean nullable: true whatsapp: type: boolean nullable: true whatsapp_call: type: boolean nullable: true type: object type: object channels: type: array items: type: object created_at: type: string format: date-time updated_at: type: string format: date-time type: object AgentGuidelineInput: description: >- One short do/don't rule. The runtime AI consults the full set of guidelines on every reply. Keep each one atomic and specific — 'Always confirm the booking date in YYYY-MM-DD format' beats 'Be professional'. properties: uuid: type: string format: uuid readOnly: true nullable: true content: description: >- Required. The rule itself, in natural language. Imperative voice works best. type: string example: >- Always confirm vehicle VIN or license plate before creating a service appointment. order: description: Display/evaluation order. Lower numbers come first. type: integer example: 0 type: object AgentNoteInput: description: >- A piece of reference knowledge the runtime AI can quote when relevant — product facts, hours, policies. Notes are passive (consulted on demand) versus guidelines which are active (applied on every turn). properties: uuid: type: string format: uuid readOnly: true nullable: true content: description: >- Required. Free-form reference text. Keep notes focused — one fact or policy per note. type: string example: >- Service appointments take 60-90 minutes for standard maintenance, 2-4 hours for warranty work. Same-day pickup is available before 4 PM. order: type: integer example: 0 type: object AgentProcedureInput: description: >- A multi-step workflow the agent can execute (e.g. 'book a service appointment'). The runtime AI walks the steps in order when it detects the relevant intent. Procedures are how you teach the agent to actually DO things instead of just talking. properties: uuid: type: string format: uuid readOnly: true nullable: true name: description: Required. Short imperative name describing what this procedure does. type: string example: Book service appointment description: description: >- When the runtime AI should invoke this procedure. Be specific about the trigger. type: string example: >- Used when the customer wants to schedule a service appointment for their vehicle. nullable: true steps: description: >- Ordered actions the agent performs. Reference an intent_uuid on a step to trigger a tool call instead of plain conversation. type: array items: properties: order: type: integer example: 1 description: type: string example: Ask the customer for their vehicle license plate or VIN. intent_uuid: description: >- Optional. UUID of an intent that, when matched, executes a tool/integration at this step (lookup, create record, send notification). type: string format: uuid nullable: true type: object type: object AgentTrainingInput: description: >- A single few-shot Q&A example. The runtime AI uses these as templates for high-quality responses to common questions. Most useful for: brand-specific phrasing, tricky FAQs, edge cases the agent keeps getting wrong. properties: uuid: type: string format: uuid readOnly: true nullable: true content: description: The customer question or scenario. type: string example: What does Volvo's standard warranty cover? intent: description: >- Optional intent label that lets the runtime AI cluster similar questions. type: string example: warranty_inquiry nullable: true response: description: >- The model answer. Match the agent's tone — what you write here is what the agent will sound like for similar questions. type: string example: >- Volvo's standard warranty covers 4 years or 100,000 km, whichever comes first, including parts and labor at any authorized service center. Would you like the details for your specific model? nullable: true type: object IntentV1: properties: intent_uuid: type: string format: uuid key: type: string name: type: string description: type: string nullable: true recommendation_actions: type: string nullable: true confidence_threshold: type: number format: float is_system: type: boolean intent_llm_handle_by_response: type: boolean webhook: properties: url: type: string nullable: true auth_token: type: string nullable: true type: object parameters: type: array items: $ref: '#/components/schemas/IntentParameterInput' created_at: type: string format: date-time updated_at: type: string format: date-time type: object AgentWebhookV1: properties: webhook_uuid: type: string format: uuid url: type: string format: uri events: type: array items: type: string enum: - conversation_status - conversation_end_report - conversation_update - voice_evaluation - text_evaluation - intent_call is_active: type: boolean has_secret: description: >- True if a secret_key is set on this webhook. The secret itself is never returned. type: boolean created_at: type: string format: date-time updated_at: type: string format: date-time type: object AgentRoutingRuleInput: description: >- Routing rules tell the runtime agent when and how to transfer a call to another extension, phone number, or agent (the IVR equivalent). The runtime AI relies on `ai_prompt` and `phrases` to decide whether a customer utterance should trigger this rule — assignments without those fields will never fire. properties: uuid: type: string format: uuid readOnly: true nullable: true detection_mode: description: >- How the AI matches customer utterances to this rule. `exact` = literal keyword (fast but narrow), `intent` = AI semantic understanding (broader, recommended), `both` = combine for max accuracy. type: string enum: - exact - intent - both example: intent trigger_keyword: description: >- Literal keyword that triggers `exact`/`both` matching. Required when detection_mode is exact or both. type: string example: sales nullable: true department_name: description: >- Human-readable label for this rule. Helps you and the AI identify what the rule is for. type: string example: Sales Department nullable: true phrases: description: >- Example customer utterances that should trigger this rule. The runtime AI uses these as training signal when detection_mode includes intent matching. Provide 3-5 varied phrasings. type: array items: type: string example: I want to talk to sales ai_prompt: description: >- Required for intent-based matching. Natural-language instructions the runtime AI uses to decide whether a customer utterance matches this rule. Without this field set, intent and both detection modes have no guidance to act on, so the rule will never trigger. Always provide concrete instructions describing what customer intent should fire this rule. type: string example: >- Detect when the customer wants to speak with the sales team — they may ask about pricing, new products, quotes, or directly mention sales. nullable: true voice_response: description: >- Message the runtime agent speaks to the customer immediately before initiating the transfer. Required. type: string example: Sure, I'll transfer you to our sales team now. One moment please. voice_on_error: description: >- Spoken when the transfer fails (busy, no answer, error). Recommended. type: string example: >- I'm sorry, I couldn't reach sales right now. Please call back later or leave a message. nullable: true voice_on_success: description: >- Spoken when the transfer completes successfully (typically only used for warm/ping-and-transfer modes). type: string example: You've been successfully connected. Have a great day. nullable: true destination_type: description: >- Where the call is sent. `extension` = SIP extension or URI (e.g. '101' or 'sip:101@domain.com'), `phone` = external phone number in E.164, `agent` = another mihu agent (set destination_agent_uuid). type: string enum: - extension - phone - agent example: extension nullable: true destination: description: >- The actual destination value. Format depends on destination_type: extension number, SIP URI, or E.164 phone. Ignored when destination_type=agent. type: string example: '101' nullable: true destination_agent_uuid: description: UUID of the target agent. Required when destination_type=agent. type: string format: uuid nullable: true transfer_type: description: >- Telephony transfer mechanism. `transfer_call` = default transfer (recommended for most cases). `forward_call` = simple forwarding. `warm_transfer_call` = the agent stays on the line and announces the caller before connecting. `blind_transfer_call` = hang up the moment the destination rings. `ping_and_transfer_call` = the agent briefly announces the caller, then transfers. type: string enum: - transfer_call - forward_call - warm_transfer_call - blind_transfer_call - ping_and_transfer_call example: transfer_call transfer_config: description: >- Optional telephony-provider-specific configuration. Free-form key/value map; consult provider docs for accepted keys. type: object nullable: true priority: description: >- Match priority. Lower numbers run first when multiple rules could match the same utterance. type: integer example: 1 is_active: type: boolean example: true type: object IntentParameterInput: required: - key properties: key: type: string example: email default: description: Default value; leave empty to ask the user type: string nullable: true type: description: >- Parameter data type. Limited to these four primitives so it maps cleanly to OpenAI's tool-schema format. type: string enum: - string - number - boolean - array example: string required: type: boolean type: object securitySchemes: bearerAuth: type: http scheme: bearer description: >- Use a Bearer token to access these API endpoints. Example: "Bearer {your-token}" ````