> ## Documentation Index > Fetch the complete documentation index at: https://developers.mindhunters.ai/llms.txt > Use this file to discover all available pages before exploring further. # Replace agent appointment settings and schedule assignments > Configures which schedules an agent uses for booking and how the runtime AI should pick between them. Each entry in `schedule_assignments` should include both `name` (a short label the AI sees, e.g. 'Service Appointment') and `description` (when to use it, e.g. 'When the customer requires routine maintenance'). These two fields are how the runtime agent decides which schedule to offer a contact — assignments created without them will be ignored by the AI's selection logic. ## OpenAPI ````yaml https://app.mindhunters.ai/docs/api-docs.json put /api/v1/agents/{uuid}/appointments 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: Availability Types description: Availability type endpoints - 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: 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 for agent activity. The Actions log 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. - 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: 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: Contact Tags description: >- Manage contact tags for your account. Each tag is identified by its `uuid`. - 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: Contact Blacklist description: Contact Blacklist - name: SIP Trunk description: SIP Trunk paths: /api/v1/agents/{uuid}/appointments: put: tags: - Agents summary: Replace agent appointment settings and schedule assignments description: >- Configures which schedules an agent uses for booking and how the runtime AI should pick between them. Each entry in `schedule_assignments` should include both `name` (a short label the AI sees, e.g. 'Service Appointment') and `description` (when to use it, e.g. 'When the customer requires routine maintenance'). These two fields are how the runtime agent decides which schedule to offer a contact — assignments created without them will be ignored by the AI's selection logic. operationId: c757f49319fc04f279d0ac81d5ae1f78 parameters: - name: uuid in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentAppointmentsInput' responses: '200': description: Appointments updated content: application/json: schema: properties: data: $ref: '#/components/schemas/AgentV1' type: object '404': description: Agent not found '422': description: Validation error security: - bearerAuth: [] components: schemas: AgentAppointmentsInput: properties: enabled: type: boolean random_assignment: type: boolean schedule_assignments: description: >- Each entry connects the agent to a schedule and tells the runtime AI when and how to use it. Always provide `name` and `description` for every assignment — without them the runtime AI cannot distinguish between schedule types when a contact asks for an appointment. type: array items: properties: schedule_uuid: description: UUID of the schedule from /api/v1/schedules. type: string format: uuid priority: description: >- Used when multiple assignments match a request — primary is preferred. type: string enum: - primary - secondary - backup status: type: string enum: - active - inactive name: description: >- Required for the AI to identify this schedule. Short label the runtime agent uses when offering this appointment type to a contact. Examples: 'Service Appointment', 'Sales Consultation', 'Test Drive'. Always set this — assignments without a name are invisible to the AI's selection logic. type: string example: Service Appointment description: description: >- Required for the AI to know when to use this schedule. Describes the customer intent or situation that should trigger this assignment. The runtime agent reads this as instructions when deciding which schedule to offer. Always set this — empty descriptions cause the AI to fall back to the primary assignment regardless of customer need. type: string example: >- When the customer requires routine maintenance, oil change, or scheduled service for their vehicle. slot_rules: $ref: '#/components/schemas/ScheduleAssignmentSlotRules' rescheduling: $ref: '#/components/schemas/ScheduleAssignmentRescheduling' cancellation: $ref: '#/components/schemas/ScheduleAssignmentCancellation' questions: $ref: '#/components/schemas/ScheduleAssignmentQuestions' approval: $ref: '#/components/schemas/ScheduleAssignmentApproval' type: object 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 ScheduleAssignmentSlotRules: description: >- Controls when slots are offered and how the AI resolves scheduling conflicts. properties: offer_slots_from: description: Minimum lead time before a slot becomes offerable to a contact. type: string enum: - now - 30_min - 1_hour - 2_hours - 3_hours - 6_hours - 24_hours example: 3_hours book_slots_from: description: >- Minimum lead time before a slot becomes bookable. Usually >= offer_slots_from. type: string enum: - now - 30_min - 1_hour - 2_hours - 3_hours - 6_hours - 24_hours example: 6_hours max_appointments_per_day: description: Daily booking cap for this assignment. Null = unlimited. type: integer minimum: 1 example: 10 nullable: true conflict_resolution_enabled: description: >- When true, the AI suggests alternative slots if the requested time is unavailable. type: boolean example: true alternative_slots_count: description: How many alternatives to offer when a conflict is detected. type: integer minimum: 1 example: 3 suggestion_priority: description: >- How alternatives are ranked: nearest in time, same calendar day, or same time slot on a different day. type: string enum: - nearest - same_day - same_time example: nearest prefer_same_day: type: boolean example: true prefer_same_time_slot: type: boolean example: false include_same_week: type: boolean example: true type: object ScheduleAssignmentRescheduling: description: When and how the contact may reschedule an existing appointment. properties: policy: description: >- always_ask = every reschedule needs human approval; auto_minor = AI can reschedule minor changes; auto_all = AI may reschedule freely within the rules. type: string enum: - always_ask - auto_minor - auto_all example: always_ask minor_change_hours: description: >- Maximum hour delta that counts as a 'minor' reschedule under the auto_minor policy. type: integer minimum: 0 example: 2 minor_change_same_day: type: boolean example: true minor_change_same_week: type: boolean example: false minor_change_same_slot: type: boolean example: false min_rescheduling_notice: description: >- Minimum advance notice before the appointment that a reschedule is allowed. type: string enum: - none - 1_hour - 2_hours - 6_hours - 24_hours example: 2_hours type: object ScheduleAssignmentCancellation: description: >- Cancellation notice window, fee policy, and whether the AI may cancel autonomously. properties: min_cancellation_notice: description: >- Minimum advance notice before the appointment that a cancellation is allowed. type: string enum: - none - 1_hour - 6_hours - 24_hours - 48_hours example: 24_hours ai_can_cancel: description: >- When true, the runtime AI may cancel an appointment on the contact's request without human approval. type: boolean example: false require_cancellation_reason: description: >- When true, the AI must capture a cancellation reason from the contact before confirming. type: boolean example: true cancellation_fee_policy: description: >- Open-ended label describing how cancellation fees are handled (e.g. 'no_fee', 'flat_fee', 'percent_of_booking'). type: string example: no_fee type: object ScheduleAssignmentQuestions: description: >- Custom intake questions the AI asks the contact when booking through this assignment. properties: inherit_from_schedule: description: >- When true, the assignment uses the parent schedule's custom_questions. Set false to override with per-assignment questions. type: boolean example: true custom_questions: description: >- Per-assignment override list. Ignored when inherit_from_schedule is true. type: array items: properties: name: type: string example: License plate type: type: string enum: - text - textarea - number - email - phone example: text description: type: string example: Vehicle license plate number for the service appointment. required: type: boolean example: true type: object type: object ScheduleAssignmentApproval: description: >- Human approval workflow for create / reschedule / cancel / notes actions. properties: require_approval: description: >- Master switch — when false, all actions are auto-approved regardless of the per-action flags. type: boolean example: true approval_threshold: description: >- Auto-approve actions if the lead time is at least this long; never = always require approval. type: string enum: - never - 15_min - 30_min - 1_hour - 24_hours example: 1_hour approval_for_create: type: boolean example: false approval_for_reschedule: type: boolean example: true approval_for_cancel: type: boolean example: true approval_for_notes: type: boolean example: false notify_calendar_owner: type: string enum: - always - approval_only - never example: always notify_admins: type: string enum: - always - approval_only - never example: always expected_response_time: description: >- Free-form label for how quickly approvers are expected to respond (e.g. '5_min', '15_min', '1_hour'). type: string example: 5_min 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 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 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}" ````