{ "openapi": "3.1.0", "info": { "title": "BlueHive HUM API", "version": "0.1.0", "summary": "Public OpenAPI contract for BlueHive HUM voice operations.", "description": "BlueHive HUM coordinates AI voice calls, call flows, voicemails, analytics, team settings, billing, and customer-managed webhooks. This public contract is limited to customer-facing API routes." }, "servers": [ { "url": "https://hum-api.bluehive.com", "description": "Production API" } ], "tags": [ { "name": "System", "description": "Public health and availability checks." }, { "name": "Authentication", "description": "Browser sign-in and sign-out flows." }, { "name": "User", "description": "Current user and organization context." }, { "name": "Organizations", "description": "Tenant profile and onboarding operations." }, { "name": "Dashboard", "description": "Overview metrics and recent activity." }, { "name": "Calls", "description": "Call history, detail views, transcripts, and live updates." }, { "name": "Flows", "description": "Reusable AI voice workflows for inbound and outbound calls." }, { "name": "Numbers", "description": "Phone number inventory and flow assignment." }, { "name": "Outbound", "description": "Outbound call creation and review." }, { "name": "Voicemails", "description": "Voicemail inbox review and triage." }, { "name": "Contacts", "description": "Caller identity, notes, and relationship context." }, { "name": "Tags", "description": "Call labels for review, filtering, and reporting." }, { "name": "Notes", "description": "Human-authored call notes and follow-up context." }, { "name": "Blocklist", "description": "Organization-level blocked phone numbers." }, { "name": "Team", "description": "Organization members, invites, and roles." }, { "name": "Webhooks", "description": "Customer-managed outbound event delivery." }, { "name": "Triggers", "description": "Inbound event triggers — opaque-token endpoints that let third-party systems fire custom external.* events into HUM to drive event-trigger agents." }, { "name": "Analytics", "description": "Aggregate usage and performance reporting." }, { "name": "Brands", "description": "Messaging brand and campaign registration drafts." }, { "name": "MCP", "description": "Customer-managed MCP tool integrations for call flows." }, { "name": "Billing", "description": "Plan, subscription, checkout, portal, and usage workflows." }, { "name": "SMS", "description": "Bi-directional SMS conversations, campaigns, opt-outs, and scheduled sends. Inbound webhooks land at /twilio/sms/:numberId; the surface here is the org-scoped REST API." } ], "paths": { "/api/health": { "get": { "tags": [ "System" ], "operationId": "getHealth", "summary": "Check API health", "description": "Returns a lightweight health response for uptime checks and deployment monitoring. This route is public and does not disclose tenant data.", "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/login": { "get": { "tags": [ "Authentication" ], "operationId": "startLogin", "summary": "Redirect to BlueHive SSO", "description": "Starts the BlueHive single sign-on flow. Pass a relative return_to path when the user should land on a specific HUM screen after authentication. The API validates and normalizes this return path before redirecting.", "security": [], "parameters": [ { "name": "return_to", "in": "query", "required": false, "description": "Relative app path to return to after login", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to BlueHive authorization" }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/logout": { "get": { "tags": [ "Authentication" ], "operationId": "logout", "summary": "Clear session and redirect to the app", "description": "Clears the HUM browser session and redirects the user back to the app. Use this for browser sign-out flows rather than attempting to delete the HTTP-only session cookie from client code.", "security": [], "responses": { "302": { "description": "Redirect after clearing session" }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/me": { "get": { "tags": [ "User" ], "operationId": "getCurrentUser", "summary": "Get signed-in user and current organization context", "description": "Returns the signed-in user, the current organization context, and role information needed by the HUM console. Tenant-scoped endpoints use the same session and organization membership model.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/orgs/current": { "get": { "tags": [ "Organizations" ], "operationId": "getCurrentOrg", "summary": "Get current organization details", "description": "Returns editable profile and configuration details for the user's current organization. Results are scoped to the active tenant and never include organizations outside the user's membership.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Organizations" ], "operationId": "updateCurrentOrg", "summary": "Update current organization details", "description": "Updates organization profile fields such as name, contact information, address, and default voice provider settings. Requires an authenticated organization member with permission to manage organization settings.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "contact_name": { "type": [ "string", "null" ], "maxLength": 200 }, "contact_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 320 }, "contact_phone": { "type": [ "string", "null" ], "maxLength": 32 }, "address_line1": { "type": [ "string", "null" ], "maxLength": 200 }, "address_line2": { "type": [ "string", "null" ], "maxLength": 200 }, "address_city": { "type": [ "string", "null" ], "maxLength": 120 }, "address_region": { "type": [ "string", "null" ], "maxLength": 120 }, "address_postal_code": { "type": [ "string", "null" ], "maxLength": 32 }, "address_country": { "type": [ "string", "null" ], "maxLength": 120 }, "default_provider": { "type": "string", "enum": [ "openai", "gemini", "elevenlabs" ] } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/orgs": { "post": { "tags": [ "Organizations" ], "operationId": "createOrg", "summary": "Create an organization during onboarding", "description": "Creates a new HUM organization during onboarding and associates the signed-in user with it. Use this after the user authenticates but before they have an active organization context.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "contact_name": { "type": [ "string", "null" ], "maxLength": 200 }, "contact_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 320 }, "contact_phone": { "type": [ "string", "null" ], "maxLength": 32 }, "address_line1": { "type": [ "string", "null" ], "maxLength": 200 }, "address_line2": { "type": [ "string", "null" ], "maxLength": 200 }, "address_city": { "type": [ "string", "null" ], "maxLength": 120 }, "address_region": { "type": [ "string", "null" ], "maxLength": 120 }, "address_postal_code": { "type": [ "string", "null" ], "maxLength": 32 }, "address_country": { "type": [ "string", "null" ], "maxLength": 120 }, "default_provider": { "type": "string", "enum": [ "openai", "gemini", "elevenlabs" ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/dashboard": { "get": { "tags": [ "Dashboard" ], "operationId": "getDashboard", "summary": "Get dashboard stats and recent calls", "description": "Returns the dashboard rollup for the current organization, including recent activity and high-level voice operations metrics. This endpoint is intended for overview screens, not detailed exports.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/calls": { "get": { "tags": [ "Calls" ], "operationId": "listCalls", "summary": "List calls for the current organization", "description": "Lists calls visible to the signed-in user in the current organization. Results can be filtered by search text, direction, status, and date range, then paginated with cursor and limit.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search phone numbers and summaries", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "Call direction", "schema": { "type": "string", "enum": [ "inbound", "outbound" ] } }, { "name": "status", "in": "query", "required": false, "description": "Call status filter", "schema": { "type": "string" } }, { "name": "read", "in": "query", "required": false, "description": "Set to 'unread' to only return calls the current user hasn't opened", "schema": { "type": "string", "enum": [ "unread" ] } }, { "name": "since", "in": "query", "required": false, "description": "Inclusive lower timestamp bound", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "required": false, "description": "Exclusive upper timestamp bound", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/calls/{id}": { "get": { "tags": [ "Calls" ], "operationId": "getCall", "summary": "Get call details, transcript, tools, summary, outcome, and recording URL", "description": "Returns one call with its transcript, tool activity, summary, outcome data, and any available customer-facing media URL. Access is limited to calls that belong to the current organization.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Call ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Calls" ], "operationId": "updateCallReadState", "summary": "Toggle the current user's read state for a call", "description": "Toggles whether the signed-in user has read this call. Read state is per-user (inbox-style): marking a call unread only affects the current user's view. Not recorded in the access log.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Call ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_read" ], "properties": { "is_read": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/calls/{id}/view": { "post": { "tags": [ "Calls" ], "operationId": "recordCallView", "summary": "Record that the current user opened the call (marks it read for them)", "description": "Records that the signed-in user opened this call and marks it read for them. Repeated views from the same user within a short window are deduplicated in the access log.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Call ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/calls/mark-all-read": { "post": { "tags": [ "Calls" ], "operationId": "markAllCallsRead", "summary": "Mark every call as read for the current user", "description": "Marks every call in the organization as read for the signed-in user. Returns the number of calls that were newly marked.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/unread-counts": { "get": { "tags": [ "Calls" ], "operationId": "getUnreadCounts", "summary": "Get unread call and voicemail counts for the current user (capped at 100)", "description": "Returns how many calls and voicemails the signed-in user has not opened yet. Counts are capped at 100 per entity; clients should render larger values as \"99+\".", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Unread counts for the current user", "content": { "application/json": { "schema": { "type": "object", "properties": { "calls": { "type": "integer", "minimum": 0, "maximum": 100 }, "voicemails": { "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "calls", "voicemails" ] } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/calls/{id}/stream": { "get": { "tags": [ "Calls" ], "operationId": "streamCallEvents", "summary": "Stream live call events as Server-Sent Events", "description": "Streams live call events for a call in progress using Server-Sent Events. Clients use this to update transcripts, tool activity, and call state without polling. Closed calls emit a terminal event and then close.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Call ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "SSE stream of call events", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/flows": { "get": { "tags": [ "Flows" ], "operationId": "listFlows", "summary": "List call flows", "description": "Lists call flows for the current organization. Flows define greetings, prompts, transfer behavior, voicemail behavior, business hours, and the automation settings used during calls.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Flows" ], "operationId": "createFlow", "summary": "Create a call flow", "description": "Creates a reusable call flow for inbound or outbound voice workflows. Start with the required name, then layer in prompts, greetings, voicemail handling, business hours, and tool configuration as needed.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "inbound", "outbound" ], "default": "inbound" }, "greeting": { "type": "string", "default": "" }, "system_prompt": { "type": "string", "default": "" }, "voice": { "type": "string", "default": "alloy" }, "voicemail_enabled": { "type": "integer", "minimum": 0, "maximum": 1, "default": 1 }, "announce_recording": { "type": "integer", "minimum": 0, "maximum": 1, "default": 1 }, "tools_json": { "type": "string", "default": "[]" }, "transfer_map_json": { "type": "string", "default": "{}" }, "flow_transfer_map_json": { "type": "string", "default": "{}" }, "outcome_schema_json": { "type": [ "string", "null" ] }, "caller_id_number_id": { "type": [ "string", "null" ] }, "voicemail_leave_message": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ], "enum": [ "openai", "gemini", "elevenlabs", null ] }, "timezone": { "type": [ "string", "null" ] }, "business_hours_json": { "type": [ "string", "null" ] }, "holidays_json": { "type": [ "string", "null" ] }, "after_hours_message": { "type": [ "string", "null" ] }, "business_hours_enabled": { "type": "integer", "minimum": 0, "maximum": 1 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/flows/{id}": { "get": { "tags": [ "Flows" ], "operationId": "getFlow", "summary": "Get a call flow", "description": "Returns a single call flow from the current organization. Use this before editing a flow so the UI can show the saved prompt, routing, voicemail, and scheduling configuration.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flow ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Flows" ], "operationId": "updateFlow", "summary": "Update a call flow", "description": "Updates an existing call flow. Changes affect future calls that use the flow; calls already in progress continue with the configuration they started with.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flow ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "inbound", "outbound" ], "default": "inbound" }, "greeting": { "type": "string", "default": "" }, "system_prompt": { "type": "string", "default": "" }, "voice": { "type": "string", "default": "alloy" }, "voicemail_enabled": { "type": "integer", "minimum": 0, "maximum": 1, "default": 1 }, "announce_recording": { "type": "integer", "minimum": 0, "maximum": 1, "default": 1 }, "tools_json": { "type": "string", "default": "[]" }, "transfer_map_json": { "type": "string", "default": "{}" }, "flow_transfer_map_json": { "type": "string", "default": "{}" }, "outcome_schema_json": { "type": [ "string", "null" ] }, "caller_id_number_id": { "type": [ "string", "null" ] }, "voicemail_leave_message": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ], "enum": [ "openai", "gemini", "elevenlabs", null ] }, "timezone": { "type": [ "string", "null" ] }, "business_hours_json": { "type": [ "string", "null" ] }, "holidays_json": { "type": [ "string", "null" ] }, "after_hours_message": { "type": [ "string", "null" ] }, "business_hours_enabled": { "type": "integer", "minimum": 0, "maximum": 1 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Flows" ], "operationId": "deleteFlow", "summary": "Delete a call flow", "description": "Deletes a call flow from the current organization. Clients should ensure the flow is no longer assigned to active phone numbers or outbound workflows before removing it.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flow ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/flows/{id}/analytics": { "get": { "tags": [ "Flows" ], "operationId": "getFlowAnalytics", "summary": "Get per-flow analytics", "description": "Returns performance and usage metrics for one call flow over a requested day window. Use this to compare flow quality, volume, and outcome trends.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flow ID", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "Window in days. Ignored when both `start` and `end` are provided.", "schema": { "type": "integer", "minimum": 1, "maximum": 365, "default": 30 } }, { "name": "start", "in": "query", "required": false, "description": "Inclusive lower bound (ISO 8601). When combined with `end`, overrides `days`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "required": false, "description": "Exclusive upper bound (ISO 8601). Requires `start`.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/flows/{id}/config": { "get": { "tags": [ "Flows" ], "operationId": "getFlowConfig", "summary": "Get a serialized call-flow configuration", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flow ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Flows" ], "operationId": "saveFlowConfig", "summary": "Validate and save a serialized call-flow configuration", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flow ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "yaml" ], "default": "json" }, "source": { "type": "string", "minLength": 1 }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "source" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/flows/{id}/versions": { "get": { "tags": [ "Flows" ], "operationId": "listFlowVersions", "summary": "List revision history for a call flow", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flow ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/flows/{id}/versions/{version}": { "get": { "tags": [ "Flows" ], "operationId": "getFlowVersion", "summary": "Get a call-flow revision snapshot", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flow ID", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "Flow version", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "Source format", "schema": { "type": "string", "enum": [ "json", "yaml" ], "default": "json" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/flows/{id}/rollback": { "post": { "tags": [ "Flows" ], "operationId": "rollbackFlow", "summary": "Roll a call flow back to a previous revision", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flow ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "version" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/flows/{id}/duplicate": { "post": { "tags": [ "Flows" ], "operationId": "duplicateFlow", "summary": "Duplicate a call flow", "description": "Creates a copy of an existing flow so teams can safely iterate on prompts or routing without changing the original workflow.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flow ID", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/flows/{id}/test-call": { "post": { "tags": [ "Flows" ], "operationId": "testFlowCall", "summary": "Place a test call for a flow", "description": "Places a controlled test call using the selected flow. This is intended for validating prompts, voice behavior, and routing before assigning the flow to production traffic.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flow ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string" } }, "required": [ "to" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/flows/ai-transcribe": { "post": { "tags": [ "Flows" ], "operationId": "transcribeFlowAudio", "summary": "Transcribe uploaded flow audio", "description": "Transcribes an uploaded audio sample for flow-building workflows. Use multipart/form-data with a single audio file field.", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "audio": { "type": "string", "format": "binary" } }, "required": [ "audio" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/numbers": { "get": { "tags": [ "Numbers" ], "operationId": "listNumbers", "summary": "List Twilio numbers", "description": "Lists phone numbers registered to the current organization, including assignment metadata used to route calls into flows.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Numbers" ], "operationId": "createNumber", "summary": "Register a Twilio number", "description": "Registers a phone number with HUM and optionally assigns it to a flow. The number must be in E.164 format and belong to the organization's voice inventory.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/numbers/sync": { "post": { "tags": [ "Numbers" ], "operationId": "syncNumbers", "summary": "Sync Twilio numbers into HUM", "description": "Refreshes the organization's phone number inventory from the connected voice provider. Use this after provisioning or changing numbers outside the HUM UI.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/numbers/available": { "get": { "tags": [ "Numbers" ], "operationId": "searchAvailableNumbers", "summary": "Search Twilio inventory for purchasable numbers", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "ISO country (default US)", "schema": { "type": "string", "default": "US" } }, { "name": "type", "in": "query", "required": false, "description": "Number type", "schema": { "type": "string", "enum": [ "Local", "TollFree" ], "default": "Local" } }, { "name": "areaCode", "in": "query", "required": false, "description": "3-digit US/CA area code", "schema": { "type": "string", "pattern": "^\\d{3}$" } }, { "name": "contains", "in": "query", "required": false, "description": "Vanity pattern (digits and *)", "schema": { "type": "string" } }, { "name": "inRegion", "in": "query", "required": false, "description": "State / region filter", "schema": { "type": "string" } }, { "name": "inLocality", "in": "query", "required": false, "description": "City filter", "schema": { "type": "string" } }, { "name": "inPostalCode", "in": "query", "required": false, "description": "Postal code filter", "schema": { "type": "string" } }, { "name": "smsEnabled", "in": "query", "required": false, "description": "Require SMS", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "mmsEnabled", "in": "query", "required": false, "description": "Require MMS", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "voiceEnabled", "in": "query", "required": false, "description": "Require Voice", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Max results", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/numbers/buy": { "post": { "tags": [ "Numbers" ], "operationId": "buyNumber", "summary": "Purchase a Twilio number into the org subaccount", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberBuyInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/numbers/{id}": { "patch": { "tags": [ "Numbers" ], "operationId": "updateNumber", "summary": "Update a Twilio number assignment", "description": "Updates the display name or flow assignment for a phone number. Assigning a flow controls which voice workflow handles inbound calls to that number.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Number ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "flow_id": { "type": [ "string", "null" ] }, "friendly_name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/outbound/calls": { "get": { "tags": [ "Outbound" ], "operationId": "listOutboundCalls", "summary": "List scheduled/outbound calls", "description": "Lists outbound calls created by the current organization. Use this to review recently placed calls, scheduled work, and call outcomes.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Outbound" ], "operationId": "createOutboundCall", "summary": "Place an outbound call", "description": "Places an outbound call using a selected flow and destination phone number. Optional task context can provide structured instructions for that specific call.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutboundCallInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/voicemails": { "get": { "tags": [ "Voicemails" ], "operationId": "listVoicemails", "summary": "List voicemails", "description": "Lists voicemails captured for the current organization. The optional filter can narrow results to heard or unheard items for inbox-style workflows. Each voicemail includes a recent-viewers summary and the most recent action taken so triage UIs can show team activity inline.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "filter", "in": "query", "required": false, "description": "Heard state filter, or 'unread' for items the current user hasn't opened", "schema": { "type": "string", "enum": [ "unheard", "heard", "unread" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/voicemails/mark-all-read": { "post": { "tags": [ "Voicemails" ], "operationId": "markAllVoicemailsRead", "summary": "Mark every voicemail as read for the current user", "description": "Marks every voicemail in the organization as read for the signed-in user. Returns the number of voicemails that were newly marked.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/voicemails/{id}": { "get": { "tags": [ "Voicemails" ], "operationId": "getVoicemail", "summary": "Get a voicemail with its activity timeline", "description": "Returns a single voicemail with its full activity timeline (views, plays, heard/unheard toggles, and operator-logged actions). Use this when opening a voicemail detail view.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Voicemail ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Voicemails" ], "operationId": "updateVoicemail", "summary": "Mark a voicemail heard/unheard (org-wide) or toggle the current user's read state", "description": "Marks a voicemail as heard or unheard (org-wide, recorded in the activity timeline), and/or toggles the signed-in user's personal read state via `is_read` (not recorded in the timeline).", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Voicemail ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "is_heard": { "type": "boolean" }, "is_read": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Voicemails" ], "operationId": "deleteVoicemail", "summary": "Delete a voicemail row", "description": "Deletes a voicemail row from the organization's voicemail list. Use this for cleanup after retention or manual triage decisions. The deletion is recorded in the org audit log.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Voicemail ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/voicemails/{id}/view": { "post": { "tags": [ "Voicemails" ], "operationId": "recordVoicemailView", "summary": "Record that the operator opened the voicemail", "description": "Records that the signed-in operator opened the voicemail. Repeated views from the same user within a short window are deduplicated to keep the activity timeline readable.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Voicemail ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/voicemails/{id}/play": { "post": { "tags": [ "Voicemails" ], "operationId": "recordVoicemailPlay", "summary": "Record that the operator played the voicemail audio", "description": "Records that the signed-in operator played the voicemail audio. Repeated plays from the same user within a short window are deduplicated.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Voicemail ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/voicemails/{id}/actions": { "post": { "tags": [ "Voicemails" ], "operationId": "logVoicemailAction", "summary": "Log a follow-up action taken on the voicemail", "description": "Logs a follow-up action the operator took on this voicemail (returned the call, sent an SMS, created a task, escalated, resolved, marked as spam, or blocked the caller). Optionally include a free-text note. By default this also marks the voicemail as heard. Note: `blocked_caller` only records the action — to actually block the number, also call `POST /api/blocklist`.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Voicemail ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "returned_call", "sent_sms", "created_task", "escalated", "resolved", "marked_spam", "blocked_caller" ] }, "note": { "type": "string", "maxLength": 2000 }, "mark_heard": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/voicemails/{id}/summarize": { "post": { "tags": [ "Voicemails" ], "operationId": "regenerateVoicemailSummary", "summary": "Regenerate the AI summary for a voicemail", "description": "Enqueues a job to (re)generate the AI summary for this voicemail. Requires a transcript of at least 20 characters. Returns 202 with `{ ok: true, queued: true }`; poll `GET /api/voicemails/{id}` to pick up the new summary once the queue worker completes.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Voicemail ID", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Summary regeneration queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "queued": { "type": "boolean" } }, "required": [ "ok", "queued" ] } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/contacts": { "get": { "tags": [ "Contacts" ], "operationId": "listContacts", "summary": "List contacts", "description": "Lists contacts for the current organization. Search by phone number, display name, role, or related notes depending on the data available.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search contacts", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Contacts" ], "operationId": "upsertContact", "summary": "Create or update a contact by phone number", "description": "Creates or updates a contact keyed by phone number. Contacts help teams recognize callers, annotate roles, and keep caller context close to call history.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/contacts/{id}": { "patch": { "tags": [ "Contacts" ], "operationId": "updateContact", "summary": "Update a contact", "description": "Updates a contact's display name, role, email, or notes. Changes are scoped to the current organization.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Contacts" ], "operationId": "deleteContact", "summary": "Delete a contact", "description": "Deletes a contact from the current organization. Historical calls remain available, but they no longer resolve to this contact record.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/contacts/backfill": { "post": { "tags": [ "Contacts" ], "operationId": "backfillContacts", "summary": "Backfill contacts from call history", "description": "Creates contact records from existing call history where possible. Use this after enabling contact management for an organization with prior call activity.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/tags": { "get": { "tags": [ "Tags" ], "operationId": "listTags", "summary": "List distinct call tags", "description": "Returns the distinct tags used by the current organization so clients can power tag pickers and filters.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/calls/{callId}/tags": { "get": { "tags": [ "Tags" ], "operationId": "listCallTags", "summary": "List tags on a call", "description": "Lists tags attached to a single call. Tags are organization-scoped labels used for workflow status, issue categories, or reporting slices.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "callId", "in": "path", "required": true, "description": "Call ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Tags" ], "operationId": "createCallTag", "summary": "Add a tag to a call", "description": "Adds a tag to a call. Use consistent names and optional colors to make call review and reporting easier across teams.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "callId", "in": "path", "required": true, "description": "Call ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagInput" } } } }, "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/calls/{callId}/tags/{name}": { "delete": { "tags": [ "Tags" ], "operationId": "deleteCallTag", "summary": "Remove a tag from a call", "description": "Removes a tag from a call without deleting that tag name from other calls in the organization.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "callId", "in": "path", "required": true, "description": "Call ID", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Tag name", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/calls/{callId}/notes": { "get": { "tags": [ "Notes" ], "operationId": "listCallNotes", "summary": "List notes on a call", "description": "Lists notes attached to a call. Notes are useful for team handoff, follow-up context, and manual review.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "callId", "in": "path", "required": true, "description": "Call ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Notes" ], "operationId": "createCallNote", "summary": "Create a note on a call", "description": "Adds a note to a call. Notes are scoped to the current organization and should contain human-readable follow-up context.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "callId", "in": "path", "required": true, "description": "Call ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "body" ] } } } }, "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/notes/{id}": { "delete": { "tags": [ "Notes" ], "operationId": "deleteNote", "summary": "Delete a note", "description": "Deletes a call note by ID. Use this to remove outdated or accidental notes from a call review timeline.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Note ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/blocklist": { "get": { "tags": [ "Blocklist" ], "operationId": "listBlockedNumbers", "summary": "List blocked numbers", "description": "Lists phone numbers blocked by the current organization. Blocked numbers are excluded from normal call handling according to organization policy.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Blocklist" ], "operationId": "createBlockedNumber", "summary": "Block a phone number", "description": "Adds a phone number to the organization blocklist with an optional reason. Use E.164 formatting for reliable matching.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "e164": { "type": "string" }, "reason": { "type": [ "string", "null" ], "maxLength": 500 } }, "required": [ "e164" ] } } } }, "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/blocklist/{id}": { "delete": { "tags": [ "Blocklist" ], "operationId": "deleteBlockedNumber", "summary": "Unblock a phone number", "description": "Removes a phone number from the organization blocklist so future calls from that number can be handled normally.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Block row ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/team": { "get": { "tags": [ "Team" ], "operationId": "listTeam", "summary": "List organization members and pending invites", "description": "Lists organization members and pending invites. Use this to render team administration screens and understand who can access the organization.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/team/invites": { "post": { "tags": [ "Team" ], "operationId": "createTeamInvite", "summary": "Invite a team member", "description": "Sends an invite to a new team member with a selected role. Organization admins should choose the least-privileged role that fits the user's work.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "admin", "operator", "viewer" ], "default": "operator" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/team/invites/{id}": { "delete": { "tags": [ "Team" ], "operationId": "revokeTeamInvite", "summary": "Revoke a pending team invite", "description": "Revokes a pending team invite before it is accepted. This does not remove existing organization members.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invite ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/team/members/{userId}": { "patch": { "tags": [ "Team" ], "operationId": "updateTeamMemberRole", "summary": "Update a team member role", "description": "Updates an existing team member's role within the current organization. Role changes take effect on subsequent authorization checks.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "operator", "viewer" ] } }, "required": [ "role" ] } } } }, "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Team" ], "operationId": "removeTeamMember", "summary": "Remove a team member", "description": "Removes a team member from the current organization. This revokes organization access but does not delete the user account.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhooks", "summary": "List outbound webhooks", "description": "Lists customer-managed outbound webhooks for the current organization. Webhooks deliver signed events from HUM to systems owned by the customer.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhook", "summary": "Create an outbound webhook", "description": "Creates a customer-managed outbound webhook. HUM generates the signing secret and returns it once so the customer can verify future deliveries.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/webhooks/{id}": { "patch": { "tags": [ "Webhooks" ], "operationId": "updateWebhook", "summary": "Update an outbound webhook", "description": "Updates webhook metadata, destination URL, event subscriptions, headers, timeout, active state, or payload template.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhook", "summary": "Delete an outbound webhook", "description": "Deletes a customer-managed webhook and stops future deliveries for that webhook configuration.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "operationId": "testWebhook", "summary": "Send a test webhook delivery", "description": "Sends a synthetic test delivery to a webhook destination so admins can confirm reachability and signature verification before relying on live events.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/webhooks/{id}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "operationId": "rotateWebhookSecret", "summary": "Rotate webhook signing secret", "description": "Rotates the signing secret for a customer-managed webhook and returns the new value once. Coordinate this with the receiving system to avoid failed verification.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookDeliveries", "summary": "List webhook delivery history", "description": "Lists delivery attempts for a webhook, including response status and retry context useful for troubleshooting customer-owned endpoints.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/webhooks/{id}/redeliver/{deliveryId}": { "post": { "tags": [ "Webhooks" ], "operationId": "redeliverWebhook", "summary": "Redeliver a webhook delivery", "description": "Retries a recorded webhook delivery attempt. Use this after fixing the receiving endpoint or recovering from a temporary outage.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID", "schema": { "type": "string" } }, { "name": "deliveryId", "in": "path", "required": true, "description": "Delivery ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/triggers": { "get": { "tags": [ "Triggers" ], "operationId": "listInboundTriggers", "summary": "List inbound event triggers", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Triggers" ], "operationId": "createInboundTrigger", "summary": "Create an inbound event trigger", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundTriggerInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/triggers/{id}": { "patch": { "tags": [ "Triggers" ], "operationId": "updateInboundTrigger", "summary": "Rename or pause/resume an inbound trigger", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Inbound trigger ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundTriggerPatch" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Triggers" ], "operationId": "deleteInboundTrigger", "summary": "Delete an inbound trigger", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Inbound trigger ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/triggers/{id}/rotate": { "post": { "tags": [ "Triggers" ], "operationId": "rotateInboundTriggerToken", "summary": "Rotate an inbound trigger token", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Inbound trigger ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/triggers/inbound/{token}": { "post": { "tags": [ "Triggers" ], "operationId": "fireInboundTrigger", "summary": "Fire an inbound event trigger", "description": "Public endpoint a third-party system (GitHub/Redmine webhook, cron, …) POSTs to in order to fire the trigger’s external.* event. Authenticated solely by the opaque per-trigger token in the path; the JSON request body becomes the event context handed to subscribed event-trigger agents.", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Opaque inbound trigger token (hit_…)", "schema": { "type": "string" } } ], "requestBody": { "description": "Arbitrary JSON object used as event context. May be omitted for a bare ping.", "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "202": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/analytics": { "get": { "tags": [ "Analytics" ], "operationId": "getAnalytics", "summary": "Get aggregate call analytics", "description": "Returns aggregate call analytics for the current organization over a configurable day window. Use this for reporting cards and operational trend views.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "Window in days. Ignored when both `start` and `end` are provided.", "schema": { "type": "integer", "minimum": 1, "maximum": 365, "default": 30 } }, { "name": "start", "in": "query", "required": false, "description": "Inclusive lower bound (ISO 8601). When combined with `end`, overrides `days`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "required": false, "description": "Exclusive upper bound (ISO 8601). Requires `start`.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/brands": { "get": { "tags": [ "Brands" ], "operationId": "getBrand", "summary": "Get A2P brand and campaign draft", "description": "Returns the organization's messaging brand and campaign draft data used for phone-number messaging registration workflows.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Brands" ], "operationId": "upsertBrand", "summary": "Create or update A2P brand draft", "description": "Creates or updates the organization's messaging brand draft. The payload should contain the customer-entered registration details needed for submission.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": { "type": "object", "additionalProperties": true }, "display_name": { "type": [ "string", "null" ] }, "ein": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/brands/submit": { "post": { "tags": [ "Brands" ], "operationId": "submitBrand", "summary": "Submit current A2P brand draft", "description": "Submits the current messaging brand draft for review. Validate customer-entered information before calling this endpoint.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/brands/campaign": { "post": { "tags": [ "Brands" ], "operationId": "upsertBrandCampaign", "summary": "Create or update A2P campaign draft", "description": "Creates or updates campaign draft details for messaging registration. Store draft updates incrementally so admins can complete the workflow over time.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/mcp-servers": { "get": { "tags": [ "MCP" ], "operationId": "listMcpServers", "summary": "List MCP servers configured for calls", "description": "Lists MCP server integrations available to call flows in the current organization. Responses indicate integration status without returning stored secrets.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "MCP" ], "operationId": "createMcpServer", "summary": "Create an MCP server integration", "description": "Creates an MCP server integration that can expose approved tools to selected call flows. Credential values are accepted on write and stored securely by HUM.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/mcp-servers/{id}": { "patch": { "tags": [ "MCP" ], "operationId": "updateMcpServer", "summary": "Update an MCP server integration", "description": "Updates an MCP server integration, including transport, URL, connector, tool allowlists, approval defaults, and enabled state.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MCP server ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "MCP" ], "operationId": "deleteMcpServer", "summary": "Delete an MCP server integration", "description": "Deletes an MCP server integration and removes it from future flow execution.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "MCP server ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/billing": { "get": { "tags": [ "Billing" ], "operationId": "getBilling", "summary": "Get plan, subscription, and usage summary", "description": "Returns plan, subscription, usage, and billing summary details for the current organization. Use this to render billing and usage screens.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/billing/checkout": { "post": { "tags": [ "Billing" ], "operationId": "createBillingCheckout", "summary": "Create a Stripe checkout session", "description": "Creates a hosted checkout session for the requested plan and returns a redirect target for the browser. Success and cancel URLs must point back to trusted app pages.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "starter", "growth", "scale" ] }, "successUrl": { "type": "string", "format": "uri" }, "cancelUrl": { "type": "string", "format": "uri" } }, "required": [ "plan" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/billing/portal": { "post": { "tags": [ "Billing" ], "operationId": "createBillingPortal", "summary": "Create a Stripe customer portal session", "description": "Creates a hosted customer portal session for managing payment details, invoices, and subscription settings outside the HUM UI.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/billing/subscription": { "patch": { "tags": [ "Billing" ], "operationId": "updateBillingSubscription", "summary": "Update subscription settings", "description": "Updates customer-controlled subscription settings, such as usage preferences or plan-related options supported by the billing workflow.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sms/conversations": { "get": { "tags": [ "SMS" ], "operationId": "listSmsConversations", "summary": "List SMS conversations", "description": "Lists SMS conversations for the current organization. Filter by status, assignee, inbound number, or a free-text search across contact E.164 and the most recent message body. Results are cursor-paginated.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by conversation status.", "schema": { "type": "string", "enum": [ "open", "snoozed", "closed" ] } }, { "name": "assigned_user_id", "in": "query", "required": false, "description": "Filter by assignee user ID.", "schema": { "type": "string" } }, { "name": "twilio_number_id", "in": "query", "required": false, "description": "Filter by inbound number.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search contact E.164 or last message body.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from a previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "SMS" ], "operationId": "createSmsConversation", "summary": "Create or fetch a SMS conversation", "description": "Creates (or fetches) a SMS conversation keyed by (twilio_number_id, contact_e164). Optionally sends an initial message through the same opt-out + quiet-hours pipeline as inbound-driven sends. Returns 201 for a new conversation, 200 for an existing one.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsConversationCreateInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sms/conversations/{id}": { "get": { "tags": [ "SMS" ], "operationId": "getSmsConversation", "summary": "Get a SMS conversation", "description": "Returns a single SMS conversation with denormalized counters and the latest metadata, including AI runtime state when present.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "SMS" ], "operationId": "patchSmsConversation", "summary": "Update SMS conversation fields", "description": "Updates one or more conversation fields (assignee, status, snoozed_until, AI pause, flow assignment, metadata). Metadata is shallow-merged so AI runtime keys (previous_response_id, outcomes, escalation_reason) are preserved across PATCH calls.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsConversationPatchInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sms/conversations/{id}/messages": { "get": { "tags": [ "SMS" ], "operationId": "listSmsMessages", "summary": "List messages in a conversation", "description": "Returns a paginated thread of inbound and outbound messages, most recent first. Use the before query parameter to walk backwards through history.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation ID", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "before", "in": "query", "required": false, "description": "Return messages older than this ISO timestamp.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "SMS" ], "operationId": "sendSmsMessage", "summary": "Send an outbound SMS or MMS", "description": "Sends an outbound SMS or MMS through sendSms(). Enforces conversation status, opt-out list, and (optionally) quiet hours. If scheduled_at is in the future the message is queued in sms_scheduled_messages and the response is 202.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsSendMessageInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sms/conversations/{id}/read": { "post": { "tags": [ "SMS" ], "operationId": "markSmsConversationRead", "summary": "Reset conversation unread_count", "description": "Resets the conversation unread_count to zero. Use this when an inbox UI displays the thread to the operator.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sms/conversations/{id}/close": { "post": { "tags": [ "SMS" ], "operationId": "closeSmsConversation", "summary": "Close a SMS conversation", "description": "Marks the conversation closed and fires conversation.closed. Inbound messages on a closed conversation reopen it automatically.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sms/conversations/{id}/reopen": { "post": { "tags": [ "SMS" ], "operationId": "reopenSmsConversation", "summary": "Reopen a SMS conversation", "description": "Sets the conversation back to open and clears any snoozed_until value.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sms/campaigns": { "get": { "tags": [ "SMS" ], "operationId": "listSmsCampaigns", "summary": "List SMS campaigns", "description": "Lists the most recent 200 SMS campaigns for the current organization, including queued, paused, and completed campaigns.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "SMS" ], "operationId": "createSmsCampaign", "summary": "Create a SMS campaign (draft)", "description": "Creates a SMS campaign in draft status. Recipients can be supplied inline or added later by inserting rows into sms_campaign_recipients. Use the launch endpoint to start sending.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsCampaignCreateInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sms/campaigns/{id}": { "get": { "tags": [ "SMS" ], "operationId": "getSmsCampaign", "summary": "Get a SMS campaign", "description": "Returns one SMS campaign with progress counters and recipient summary.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sms/campaigns/{id}/launch": { "post": { "tags": [ "SMS" ], "operationId": "launchSmsCampaign", "summary": "Launch a draft or paused campaign", "description": "Moves the campaign from draft or paused into queued. The cron dispatcher picks it up on the next minute boundary, then sends throttled by throttle_per_minute.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sms/campaigns/{id}/cancel": { "post": { "tags": [ "SMS" ], "operationId": "cancelSmsCampaign", "summary": "Cancel an active campaign", "description": "Stops further sends from the campaign. Messages already handed to Twilio still deliver.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sms/opt-outs": { "get": { "tags": [ "SMS" ], "operationId": "listSmsOptOuts", "summary": "List SMS opt-outs", "description": "Lists active opt-outs for the current organization. Carrier keywords (STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT) populate this list automatically.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "SMS" ], "operationId": "createSmsOptOut", "summary": "Manually opt out a contact", "description": "Adds a manual opt-out for a contact E.164. Fires sms.opt_out and immediately blocks further outbound sends to that number.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsOptOutCreateInput" } } } }, "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sms/opt-outs/{e164}": { "delete": { "tags": [ "SMS" ], "operationId": "deleteSmsOptOut", "summary": "Remove a SMS opt-out", "description": "Removes a contact from the opt-out list (e.g. after explicit re-consent). Fires sms.opt_in. URL-encode the leading + on the path parameter.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "e164", "in": "path", "required": true, "description": "Contact E.164 (URL-encode the leading +).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sms/scheduled": { "get": { "tags": [ "SMS" ], "operationId": "listSmsScheduled", "summary": "List pending scheduled sends", "description": "Lists currently pending scheduled sends — manual schedules, AI follow-ups, and quiet-hours-deferred messages — for the current organization.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by scheduled-message status.", "schema": { "type": "string", "enum": [ "pending", "sent", "failed", "cancelled" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sms/scheduled/{id}": { "delete": { "tags": [ "SMS" ], "operationId": "cancelSmsScheduled", "summary": "Cancel a pending scheduled send", "description": "Cancels a pending scheduled message before the cron tick picks it up. Already-claimed rows in flight cannot be cancelled.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Scheduled message ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/widget-tokens": { "get": { "tags": [ "Widget Tokens" ], "operationId": "listWidgetTokens", "summary": "List embeddable widget tokens", "description": "Returns the org-issued public-key tokens that authorize the BlueHive embeddable voice widget on partner sites. Admin-only.", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Widget Tokens" ], "operationId": "createWidgetToken", "summary": "Create a widget token", "description": "Mints a new `whk_*` public key, captcha config, origin allowlist, rate limit and spend cap for the embeddable voice widget. Admin-only.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "default_flow_id": { "type": [ "string", "null" ] }, "allowed_origins": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "minItems": 1, "maxItems": 20, "description": "Exact-match origin allowlist (scheme + host + port). Wildcards are rejected." }, "captcha_provider": { "type": "string", "enum": [ "turnstile", "none" ], "default": "turnstile" }, "captcha_site_key": { "type": [ "string", "null" ], "maxLength": 120 }, "daily_spend_cap_cents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000000, "description": "Per-org daily spend ceiling in USD cents. `null` means no cap." }, "per_ip_rate_per_min": { "type": "integer", "minimum": 1, "maximum": 60, "default": 3 }, "max_session_seconds": { "type": "integer", "minimum": 30, "maximum": 1800, "default": 300 }, "lead_fields": { "type": "array", "maxItems": 6, "items": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "name", "email", "phone", "notes" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "required": { "type": "boolean", "default": false }, "type": { "type": "string", "enum": [ "text", "email", "tel", "textarea" ], "default": "text" } }, "required": [ "name", "label" ] } }, "active": { "type": "boolean", "default": true } }, "required": [ "name", "allowed_origins" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/widget-tokens/{id}": { "patch": { "tags": [ "Widget Tokens" ], "operationId": "updateWidgetToken", "summary": "Update a widget token", "description": "Updates widget-token settings (origins, captcha, caps, lead fields, active flag). Admin-only.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Widget token ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "default_flow_id": { "type": [ "string", "null" ] }, "allowed_origins": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "minItems": 1, "maxItems": 20, "description": "Exact-match origin allowlist (scheme + host + port). Wildcards are rejected." }, "captcha_provider": { "type": "string", "enum": [ "turnstile", "none" ], "default": "turnstile" }, "captcha_site_key": { "type": [ "string", "null" ], "maxLength": 120 }, "daily_spend_cap_cents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000000, "description": "Per-org daily spend ceiling in USD cents. `null` means no cap." }, "per_ip_rate_per_min": { "type": "integer", "minimum": 1, "maximum": 60, "default": 3 }, "max_session_seconds": { "type": "integer", "minimum": 30, "maximum": 1800, "default": 300 }, "lead_fields": { "type": "array", "maxItems": 6, "items": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "name", "email", "phone", "notes" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "required": { "type": "boolean", "default": false }, "type": { "type": "string", "enum": [ "text", "email", "tel", "textarea" ], "default": "text" } }, "required": [ "name", "label" ] } }, "active": { "type": "boolean", "default": true } }, "required": [] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/widget-tokens/{id}/revoke": { "post": { "tags": [ "Widget Tokens" ], "operationId": "revokeWidgetToken", "summary": "Revoke a widget token", "description": "Marks the widget token inactive and stamps `revoked_at`. Future public sessions for this token return 404. Admin-only.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Widget token ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/widget-tokens/{id}/leads": { "get": { "tags": [ "Widget Tokens" ], "operationId": "listWidgetTokenLeads", "summary": "Recent leads captured by a widget token", "description": "Returns the most recent lead-form submissions associated with this widget token (name, email, phone, notes, origin and the linked call). Admin-only.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Widget token ID", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of leads to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/widget-tokens/{id}/usage": { "get": { "tags": [ "Widget Tokens" ], "operationId": "getWidgetTokenUsage", "summary": "Daily usage rollup for widget calls (last 30 days)", "description": "Returns the per-day call count, total seconds and estimated cents for the org’s widget usage. Used to render the daily spend cap context. Admin-only.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Widget token ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "bh_hum_session", "description": "HTTP-only HUM session cookie set by the BlueHive SSO flow." } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true }, "OkResponse": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": true }, "VoicemailAiSummary": { "type": "object", "description": "AI-generated digest of a voicemail. Populated asynchronously after the transcript is produced. When `generated_at` is null and `error` is set, the last generation attempt failed and the caller can hit POST /api/voicemails/{id}/summarize to retry.", "properties": { "tldr": { "type": "string" }, "sentiment": { "type": [ "string", "null" ], "enum": [ "positive", "neutral", "negative", "mixed", null ] }, "urgency": { "type": [ "string", "null" ], "enum": [ "low", "normal", "high", "urgent", null ] }, "intended_recipient": { "type": [ "string", "null" ] }, "caller_name": { "type": [ "string", "null" ] }, "callback_number_e164": { "type": [ "string", "null" ] }, "categories": { "type": "array", "items": { "type": "string" } }, "entities": { "type": "array", "items": { "type": "string" } }, "action_items": { "type": "array", "items": { "type": "string" } }, "language": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "prompt_version": { "type": [ "integer", "null" ] }, "generated_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "attempt_count": { "type": "integer" } }, "required": [ "tldr", "categories", "entities", "action_items", "attempt_count" ] }, "OrganizationInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "contact_name": { "type": [ "string", "null" ], "maxLength": 200 }, "contact_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 320 }, "contact_phone": { "type": [ "string", "null" ], "maxLength": 32 }, "address_line1": { "type": [ "string", "null" ], "maxLength": 200 }, "address_line2": { "type": [ "string", "null" ], "maxLength": 200 }, "address_city": { "type": [ "string", "null" ], "maxLength": 120 }, "address_region": { "type": [ "string", "null" ], "maxLength": 120 }, "address_postal_code": { "type": [ "string", "null" ], "maxLength": 32 }, "address_country": { "type": [ "string", "null" ], "maxLength": 120 }, "default_provider": { "type": "string", "enum": [ "openai", "gemini", "elevenlabs" ] } }, "required": [ "name" ] }, "FlowInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "inbound", "outbound" ], "default": "inbound" }, "greeting": { "type": "string", "default": "" }, "system_prompt": { "type": "string", "default": "" }, "voice": { "type": "string", "default": "alloy" }, "voicemail_enabled": { "type": "integer", "minimum": 0, "maximum": 1, "default": 1 }, "announce_recording": { "type": "integer", "minimum": 0, "maximum": 1, "default": 1 }, "tools_json": { "type": "string", "default": "[]" }, "transfer_map_json": { "type": "string", "default": "{}" }, "flow_transfer_map_json": { "type": "string", "default": "{}" }, "outcome_schema_json": { "type": [ "string", "null" ] }, "caller_id_number_id": { "type": [ "string", "null" ] }, "voicemail_leave_message": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ], "enum": [ "openai", "gemini", "elevenlabs", null ] }, "timezone": { "type": [ "string", "null" ] }, "business_hours_json": { "type": [ "string", "null" ] }, "holidays_json": { "type": [ "string", "null" ] }, "after_hours_message": { "type": [ "string", "null" ] }, "business_hours_enabled": { "type": "integer", "minimum": 0, "maximum": 1 } }, "required": [ "name" ] }, "SerializedFlowConfigInput": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "yaml" ], "default": "json" }, "source": { "type": "string", "minLength": 1 }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "source" ] }, "FlowRollbackInput": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "version" ] }, "NumberInput": { "type": "object", "properties": { "sid": { "type": "string", "pattern": "^PN[0-9a-fA-F]{32}$" }, "e164": { "type": "string", "pattern": "^\\+[1-9]\\d{7,14}$" }, "friendly_name": { "type": "string", "maxLength": 120 }, "flow_id": { "type": [ "string", "null" ] } }, "required": [ "sid", "e164" ] }, "NumberBuyInput": { "type": "object", "properties": { "phoneNumber": { "type": "string", "pattern": "^\\+[1-9]\\d{7,14}$" }, "friendly_name": { "type": "string", "maxLength": 120 }, "flow_id": { "type": [ "string", "null" ] }, "sms_flow_id": { "type": [ "string", "null" ] } }, "required": [ "phoneNumber" ] }, "OutboundCallInput": { "type": "object", "properties": { "flow_id": { "type": "string", "minLength": 1 }, "to": { "type": "string", "pattern": "^\\+[1-9]\\d{7,14}$" }, "task_context": { "type": "object", "additionalProperties": true }, "caller_id_number_id": { "type": [ "string", "null" ] }, "force": { "type": "boolean" } }, "required": [ "flow_id", "to" ] }, "ContactInput": { "type": "object", "properties": { "e164": { "type": "string", "minLength": 2, "maxLength": 32 }, "display_name": { "type": [ "string", "null" ], "maxLength": 200 }, "role": { "type": [ "string", "null" ], "maxLength": 120 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 320 }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 } } }, "TagInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "color": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{3,8}$" } }, "required": [ "name" ] }, "WebhookInput": { "type": "object", "properties": { "label": { "type": [ "string", "null" ], "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "active": { "type": "boolean", "default": true }, "custom_headers": { "type": [ "object", "null" ], "additionalProperties": { "type": "string", "maxLength": 512 } }, "timeout_ms": { "type": "integer", "minimum": 1000, "maximum": 60000 }, "template": { "type": "string" } }, "required": [ "url" ] }, "InboundTriggerInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Human label shown in the UI (e.g. \"GitHub issues\")." }, "event_type": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Event this trigger fires. Free-form; normalized server-side to external. (e.g. \"GitHub issue opened\" -> external.github.issue.opened)." }, "active": { "type": "boolean", "default": true } }, "required": [ "name", "event_type" ] }, "InboundTriggerPatch": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "active": { "type": "boolean" } } }, "McpServerInput": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9_-]+$" }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "flow_id": { "type": [ "string", "null" ] }, "transport": { "type": "string", "enum": [ "hosted", "worker_streamable_http" ], "default": "hosted" }, "server_url": { "type": [ "string", "null" ], "format": "uri" }, "connector_id": { "type": [ "string", "null" ], "maxLength": 128 }, "auth_type": { "type": "string", "enum": [ "none", "bearer", "header", "oauth_token" ], "default": "none" }, "allowed_tools_json": { "type": [ "string", "null" ] }, "auto_approve_tools_json": { "type": [ "string", "null" ] }, "require_approval_default": { "type": "string", "enum": [ "never", "always" ], "default": "always" }, "enabled": { "type": "integer", "minimum": 0, "maximum": 1, "default": 1 } }, "required": [ "label" ] }, "SmsMediaItem": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "content_type": { "type": "string", "maxLength": 120 } }, "required": [ "url" ] }, "SmsConversationCreateInput": { "type": "object", "properties": { "twilio_number_id": { "type": "string", "minLength": 1 }, "contact_e164": { "type": "string", "pattern": "^\\+[1-9]\\d{7,14}$" }, "flow_id": { "type": [ "string", "null" ] }, "assigned_user_id": { "type": [ "string", "null" ] }, "initial_message": { "type": "object", "properties": { "body": { "type": "string", "maxLength": 1600 }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/SmsMediaItem" }, "maxItems": 10 }, "honor_quiet_hours": { "type": "boolean", "default": false } } } }, "required": [ "twilio_number_id", "contact_e164" ] }, "SmsConversationPatchInput": { "type": "object", "properties": { "ai_paused": { "type": "boolean" }, "assigned_user_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "snoozed", "closed" ] }, "snoozed_until": { "type": [ "string", "null" ], "format": "date-time" }, "flow_id": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true, "description": "Shallow-merged into the existing metadata via JSON Merge Patch (RFC 7396). Send null on a key to delete it." } } }, "SmsSendMessageInput": { "type": "object", "properties": { "body": { "type": "string", "maxLength": 1600 }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/SmsMediaItem" }, "maxItems": 10 }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When set in the future, the message is queued in sms_scheduled_messages instead of sent immediately. Maximum horizon is 90 days." }, "purpose": { "type": [ "string", "null" ], "maxLength": 120 }, "honor_quiet_hours": { "type": "boolean", "default": false, "description": "When true, sends outside business hours are auto-deferred. Defaults to false for human-initiated REST sends." } } }, "SmsCampaignRecipientInput": { "type": "object", "properties": { "contact_e164": { "type": "string", "pattern": "^\\+[1-9]\\d{7,14}$" }, "body": { "type": [ "string", "null" ], "maxLength": 1600 }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/SmsMediaItem" }, "maxItems": 10 } }, "required": [ "contact_e164" ] }, "SmsCampaignCreateInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "twilio_number_id": { "type": "string", "minLength": 1 }, "flow_id": { "type": [ "string", "null" ] }, "body_template": { "type": "string", "maxLength": 1600 }, "throttle_per_minute": { "type": "integer", "minimum": 1, "maximum": 600, "default": 30 }, "scheduled_start_at": { "type": [ "string", "null" ], "format": "date-time" }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/SmsCampaignRecipientInput" } } }, "required": [ "name", "twilio_number_id", "body_template" ] }, "SmsOptOutCreateInput": { "type": "object", "properties": { "e164": { "type": "string", "pattern": "^\\+[1-9]\\d{7,14}$" }, "reason": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "e164" ] } } } }