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