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