{ "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": "Automation", "description": "Revocable credentials used by MCP clients and direct API integrations." }, { "name": "Site Administration", "description": "Cross-tenant provisioning available only to explicitly scoped site administrators." }, { "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, with run IDs, signed result callbacks, and a polling endpoint for the results." }, { "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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/api-keys": { "get": { "tags": [ "Automation" ], "operationId": "listApiKeys", "summary": "List organization API keys", "description": "Lists API keys issued for the current organization. Plaintext secrets are never returned; use the prefix and last-used timestamp to identify integrations before revoking them.", "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": [ "Automation" ], "operationId": "createApiKey", "summary": "Issue an organization API key", "description": "Issues a revocable organization API key and returns its plaintext token exactly once. This operation requires a signed-in human organization administrator and cannot itself be called with an API key.", "security": [ { "sessionCookie": [] } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyInput" } } } }, "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/api-keys/{id}": { "delete": { "tags": [ "Automation" ], "operationId": "revokeApiKey", "summary": "Revoke an organization API key", "description": "Revokes an organization API key immediately. Existing MCP and REST requests using that key fail authentication after revocation. This operation requires a signed-in human organization administrator.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "API key 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/admin/orgs": { "get": { "tags": [ "Site Administration" ], "operationId": "listAdminOrgs", "summary": "List organizations as a site administrator", "description": "Lists organizations across HUM for a site administrator. API keys must carry the site:admin scope and belong to a user who remains a site administrator.", "security": [ { "sessionCookie": [] }, { "humApiKey": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Name or contact email search", "schema": { "type": "string" } }, { "name": "plan", "in": "query", "required": false, "description": "Plan filter", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Subscription status filter", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "required": false, "description": "Include only archived organizations", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Page size", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "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": [ "Site Administration" ], "operationId": "provisionOrg", "summary": "Provision an organization for an existing user", "description": "Creates an organization for an existing HUM user and grants that user the admin role. The owner must have signed into HUM at least once. Requires site-admin access; use this operation for automated provisioning rather than the single-user onboarding endpoint.", "security": [ { "sessionCookie": [] }, { "humApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable unique key for this provisioning request. Reuse it when retrying after a timeout.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminOrgInput" } } } }, "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" } } } }, "409": { "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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}/caller-history": { "get": { "tags": [ "Calls" ], "operationId": "getCallerHistory", "summary": "Get the other party's prior call history (repeat-caller timeline)", "security": [ { "sessionCookie": [] }, { "humApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Call ID", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "Filter to a single reason/category", "schema": { "type": "string" } }, { "name": "unresolved", "in": "query", "required": false, "description": "Only return prior calls with an unresolved / follow-up outcome", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Max prior calls to return (default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "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}/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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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}/event-runs": { "get": { "tags": [ "Flows" ], "operationId": "listAgentRuns", "summary": "List background runs for an event agent", "description": "Lists recent background runs for an event-trigger agent, newest first. Use this to review what an agent has been working on, whether runs are succeeding, and how long they take. Each run reports its tool calls as name, status, and latency only — tool arguments and raw tool results are never returned.", "security": [ { "sessionCookie": [] }, { "humApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent (flow) ID", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum runs to return, newest first.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "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" } } } } } }, "post": { "tags": [ "Flows" ], "operationId": "assignAgentTask", "summary": "Assign a background task to an event agent", "description": "Assigns a background task to an event-trigger agent and returns immediately with a run ID. The agent works asynchronously against the supplied context using its configured tools and knowledge base; poll getAgentRun for the result, or subscribe an outbound webhook to `agent.run.completed`. The supplied input must serialize to at most 65536 bytes. Supply `task_id` to make retries safe: for one hour after a task is first submitted under that key, replaying it returns the same run (with `deduplicated: true`) instead of running the agent again, whether the original is still working or already finished. Runs that end in `failed` or `tool_loop_exceeded` release the key so a genuine retry starts a new attempt. Returns 503 when background agent runs are unavailable and 500 when dispatch fails.", "security": [ { "sessionCookie": [] }, { "humApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent (flow) ID", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "The agent's working context. A string is treated as a plain-language task; an object is passed through as structured context. Must serialize to at most 65536 bytes.", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "object", "additionalProperties": true } ] }, "task_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Idempotency key. For one hour after a task is first submitted under this key, replaying it returns that same run instead of starting a new one." } } } } } }, "responses": { "202": { "description": "Accepted for background processing", "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" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/flows/{id}/event-runs/{runId}": { "get": { "tags": [ "Flows" ], "operationId": "getAgentRun", "summary": "Get the status and result of an agent run", "description": "Returns the status and result of a single agent run. `done` is false while the run is queued and true once it settles as completed, failed, no_op, or tool_loop_exceeded. Poll this after assignAgentTask rather than holding a request open.", "security": [ { "sessionCookie": [] }, { "humApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent (flow) ID", "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "description": "Agent run 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}/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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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/{id}/rotate-callback-secret": { "post": { "tags": [ "Triggers" ], "operationId": "rotateInboundTriggerCallbackSecret", "summary": "Rotate the callback signing secret", "description": "Mints a fresh HMAC secret used to sign result-callback deliveries for this trigger and returns it exactly once. Receivers verifying X-HUM-Signature must adopt the new value.", "security": [ { "sessionCookie": [] }, { "humApiKey": [] } ], "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/{id}/runs": { "get": { "tags": [ "Triggers" ], "operationId": "listInboundTriggerRuns", "summary": "List recent agent runs started by a trigger", "description": "Returns the most recent agent runs this inbound trigger started, newest first, including run status, output, latency, and the callback delivery outcome. Admin-only.", "security": [ { "sessionCookie": [] }, { "humApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Inbound trigger ID", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of runs to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "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. Reserved body fields: `_callback` (`{\"url\": \"https://…\"}` or a plain string) overrides the trigger’s default result-callback URL for this request and is stripped before the agent sees the payload; `id` enables idempotent redelivery (same id within an hour returns the original run’s result). The 202 response lists the agent runs started so callers can poll or correlate callbacks. When a callback URL is configured, HUM POSTs the signed agent.run.completed payload (HMAC-SHA256 of the raw body in X-HUM-Signature, using the trigger’s callback secret) to it when each run finishes.", "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. `_callback` and `id` are reserved (see description).", "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "202": { "description": "Event accepted; lists the agent runs started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundTriggerFireResponse" } } } }, "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}/runs/{runId}": { "get": { "tags": [ "Triggers" ], "operationId": "pollInboundTriggerRun", "summary": "Poll the status/result of an agent run", "description": "Public polling endpoint for callers that can’t receive callbacks. Authenticated by the same opaque trigger token; only runs started by this trigger are visible. While the agent is working, status is `queued`; once finished the response carries the full output, tool-call summary, token usage, and — when a callback was configured — its delivery outcome.", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Opaque inbound trigger token (hit_…)", "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "description": "Run ID returned by the fire response", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current run state and result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRunStatus" } } } }, "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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": [] }, { "humApiKey": [] } ], "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" } } } } } } } }, "webhooks": { "agent.run.completed": { "post": { "summary": "Agent run result callback", "description": "POSTed to an inbound trigger’s callback URL (or the per-request _callback override) when an event-agent run finishes, and to org webhooks subscribed to the agent.run.completed event. Verify X-HUM-Signature (sha256=, HMAC-SHA256 of the raw body) before trusting the payload. Trigger callback deliveries also carry X-HUM-Run-ID and X-HUM-Trigger-ID correlation headers; org-webhook deliveries do not — read run_id and trigger_id from the payload’s data object instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRunCompletedPayload" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." } } } } }, "components": { "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "bh_hum_session", "description": "HTTP-only HUM session cookie set by the BlueHive SSO flow." }, "humApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "hum_live_*", "description": "Revocable HUM API key issued by an organization administrator. Keys carry an org role plus org:read, org:write, and optional site:admin scopes." } }, "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 }, "ApiKeyInput": { "type": "object", "required": [ "name" ], "allOf": [ { "if": { "properties": { "role": { "const": "viewer" } }, "required": [ "role" ] }, "then": { "properties": { "scopes": { "items": { "const": "org:read" } } } } }, { "if": { "properties": { "scopes": { "contains": { "const": "site:admin" } } }, "required": [ "scopes" ] }, "then": { "properties": { "scopes": { "allOf": [ { "contains": { "const": "org:read" } }, { "contains": { "const": "org:write" } } ] } } } } ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "role": { "type": "string", "enum": [ "admin", "operator", "viewer" ], "default": "operator" }, "scopes": { "type": "array", "minItems": 1, "uniqueItems": true, "description": "Defaults to org:read for viewer keys and org:read plus org:write otherwise. site:admin requires both companion scopes.", "items": { "type": "string", "enum": [ "org:read", "org:write", "site:admin" ] } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "AdminOrgInput": { "type": "object", "required": [ "name", "ownerEmail" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "ownerEmail": { "type": "string", "format": "email" }, "plan": { "type": "string", "enum": [ "trial", "starter", "growth", "scale", "enterprise" ], "default": "trial" }, "adminNotes": { "type": "string", "maxLength": 2000 } } }, "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 }, "callback_url": { "type": [ "string", "null" ], "maxLength": 1024, "description": "Default URL the signed agent-run result is POSTed to when a run finishes. Must be a public https:// URL. Callers can override per request via the reserved _callback body field." } }, "required": [ "name", "event_type" ] }, "InboundTriggerPatch": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "active": { "type": "boolean" }, "callback_url": { "type": [ "string", "null" ], "maxLength": 1024, "description": "Default result-callback URL. null clears it." } } }, "InboundTriggerFireResponse": { "type": "object", "description": "Returned by the public fire endpoint with the agent runs it started.", "properties": { "ok": { "type": "boolean" }, "event_type": { "type": "string" }, "runs": { "type": "array", "description": "One entry per subscribed agent the event started. Empty when no agent subscribes to this event.", "items": { "type": "object", "properties": { "agent_id": { "type": "string" }, "run_id": { "type": "string" }, "status_url": { "type": "string", "description": "Polling URL for this run (same token auth)." } }, "required": [ "agent_id", "run_id", "status_url" ] } }, "callback_url": { "type": [ "string", "null" ], "description": "Effective result-callback URL for these runs, if any." } }, "required": [ "ok", "event_type", "runs" ] }, "AgentRunStatus": { "type": "object", "description": "Current state of an event-agent run, as returned by the polling endpoint.", "properties": { "run_id": { "type": "string" }, "agent_id": { "type": "string" }, "event_type": { "type": "string" }, "trigger_ref": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "completed", "failed", "no_op", "tool_loop_exceeded" ] }, "output": { "type": [ "string", "null" ], "description": "The agent’s final output text." }, "tool_calls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "latency_ms": { "type": [ "integer", "null" ] } } } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } }, "latency_ms": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "callback": { "type": [ "object", "null" ], "description": "Result-callback delivery outcome, when a callback was configured.", "properties": { "url": { "type": "string" }, "status": { "type": [ "string", "null" ], "enum": [ "pending", "delivered", "failed", null ] }, "status_code": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "created_at": { "type": "string" } }, "required": [ "run_id", "agent_id", "event_type", "status" ] }, "AgentRunCompletedPayload": { "type": "object", "description": "Body POSTed to result-callback URLs and to org webhooks subscribed to agent.run.completed. Sign-verified via X-HUM-Signature: sha256= — an HMAC-SHA256 of the raw body using the trigger’s callback secret (callbacks) or the webhook’s signing secret (org webhooks).", "properties": { "type": { "type": "string", "const": "agent.run.completed" }, "org_id": { "type": "string" }, "delivered_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "run_id": { "type": "string" }, "agent_id": { "type": "string" }, "agent_name": { "type": [ "string", "null" ] }, "event_type": { "type": "string" }, "trigger_ref": { "type": [ "string", "null" ] }, "trigger_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "completed", "failed", "no_op", "tool_loop_exceeded" ] }, "output": { "type": [ "string", "null" ], "description": "Final output text (clamped for delivery; poll the status URL for the full text)." }, "tool_calls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "latency_ms": { "type": [ "integer", "null" ] } } } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } }, "latency_ms": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "deduped": { "type": "boolean", "description": "Present and true when an idempotent redelivery matched a previous run; original_run_id identifies it." }, "original_run_id": { "type": "string" }, "completed_at": { "type": "string", "format": "date-time" } }, "required": [ "run_id", "agent_id", "event_type", "status" ] } }, "required": [ "type", "org_id", "delivered_at", "data" ] }, "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" ] } } } }