openapi: 3.0.3
info:
  title: GoMobile Platform API
  description: >-
    Omni-channel communication platform with centralized contacts, call flows,
    insights, and reporting. Build voice campaigns, manage audiences, and
    orchestrate automated calling programs.
  version: 1.0.0
  contact:
    name: GoMobile Platform Team
  x-gitbook-description-document:
    object: document
    data:
      schemaVersion: 9
    nodes:
      - object: block
        type: paragraph
        isVoid: false
        data: {}
        nodes:
          - object: text
            leaves:
              - object: leaf
                text: >-
                  Omni-channel communication platform with centralized contacts,
                  call flows, insights, and reporting. Build voice campaigns,
                  manage audiences, and orchestrate automated calling programs.
                marks: []
  x-gitbook-description-html: >-
    <p>Omni-channel communication platform with centralized contacts, call
    flows, insights, and reporting. Build voice campaigns, manage audiences, and
    orchestrate automated calling programs.</p>
servers:
  - url: https://api.gomobile.ma/api
    description: Production
    x-gitbook-description-html: <p>Production</p>
security:
  - BearerAuth: []
tags:
  - name: Auth
    description: Authentication and session management
    x-gitbook-description-document:
      object: document
      data:
        schemaVersion: 9
      nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
            - object: text
              leaves:
                - object: leaf
                  text: Authentication and session management
                  marks: []
    x-gitbook-description-html: <p>Authentication and session management</p>
  - name: Users
    description: Current user profile
    x-gitbook-description-document:
      object: document
      data:
        schemaVersion: 9
      nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
            - object: text
              leaves:
                - object: leaf
                  text: Current user profile
                  marks: []
    x-gitbook-description-html: <p>Current user profile</p>
  - name: Contacts
    description: Contact management and custom attributes
    x-gitbook-description-document:
      object: document
      data:
        schemaVersion: 9
      nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
            - object: text
              leaves:
                - object: leaf
                  text: Contact management and custom attributes
                  marks: []
    x-gitbook-description-html: <p>Contact management and custom attributes</p>
  - name: Custom Attributes
    description: Define custom fields for contacts
    x-gitbook-description-document:
      object: document
      data:
        schemaVersion: 9
      nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
            - object: text
              leaves:
                - object: leaf
                  text: Define custom fields for contacts
                  marks: []
    x-gitbook-description-html: <p>Define custom fields for contacts</p>
  - name: Audiences
    description: Audience segments for campaigns
    x-gitbook-description-document:
      object: document
      data:
        schemaVersion: 9
      nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
            - object: text
              leaves:
                - object: leaf
                  text: Audience segments for campaigns
                  marks: []
    x-gitbook-description-html: <p>Audience segments for campaigns</p>
  - name: Audio
    description: Audio file management for call flows
    x-gitbook-description-document:
      object: document
      data:
        schemaVersion: 9
      nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
            - object: text
              leaves:
                - object: leaf
                  text: Audio file management for call flows
                  marks: []
    x-gitbook-description-html: <p>Audio file management for call flows</p>
  - name: Dictionaries
    description: Sound dictionaries for dynamic audio playback
    x-gitbook-description-document:
      object: document
      data:
        schemaVersion: 9
      nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
            - object: text
              leaves:
                - object: leaf
                  text: Sound dictionaries for dynamic audio playback
                  marks: []
    x-gitbook-description-html: <p>Sound dictionaries for dynamic audio playback</p>
  - name: Flows
    description: Call flow definitions and execution
    x-gitbook-description-document:
      object: document
      data:
        schemaVersion: 9
      nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
            - object: text
              leaves:
                - object: leaf
                  text: Call flow definitions and execution
                  marks: []
    x-gitbook-description-html: <p>Call flow definitions and execution</p>
  - name: Call Requests
    description: Ad-hoc call requests with retry strategies
    x-gitbook-description-document:
      object: document
      data:
        schemaVersion: 9
      nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
            - object: text
              leaves:
                - object: leaf
                  text: Ad-hoc call requests with retry strategies
                  marks: []
    x-gitbook-description-html: <p>Ad-hoc call requests with retry strategies</p>
  - name: Call Reports
    description: Call execution reports and analytics
    x-gitbook-description-document:
      object: document
      data:
        schemaVersion: 9
      nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
            - object: text
              leaves:
                - object: leaf
                  text: Call execution reports and analytics
                  marks: []
    x-gitbook-description-html: <p>Call execution reports and analytics</p>
  - name: Programs
    description: Calling campaign management
    x-gitbook-description-document:
      object: document
      data:
        schemaVersion: 9
      nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
            - object: text
              leaves:
                - object: leaf
                  text: Calling campaign management
                  marks: []
    x-gitbook-description-html: <p>Calling campaign management</p>
  - name: Program Executions
    description: Campaign execution lifecycle
    x-gitbook-description-document:
      object: document
      data:
        schemaVersion: 9
      nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
            - object: text
              leaves:
                - object: leaf
                  text: Campaign execution lifecycle
                  marks: []
    x-gitbook-description-html: <p>Campaign execution lifecycle</p>
paths:
  /auth/login:
    post:
      tags:
        - Auth
      summary: Login
      description: Authenticate with email and password. For dashboard access only.
      operationId: login
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginRequest"
            example:
              email: john.doe@example.com
              password: SecurePass123!
      responses:
        "200":
          description: Login successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthResponse"
          x-gitbook-description-html: <p>Login successful</p>
        "401":
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          x-gitbook-description-html: <p>Invalid credentials</p>
      x-gitbook-description-html: <p>Authenticate with email and password. For dashboard access only.</p>
  /auth/refresh:
    post:
      tags:
        - Auth
      summary: Refresh tokens
      description: Exchange refresh token for new access and refresh tokens.
      operationId: refreshToken
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RefreshTokenRequest"
            example:
              refresh_token: dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...
      responses:
        "200":
          description: Tokens refreshed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthResponse"
              example:
                access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                refresh_token: bmV3IHJlZnJlc2ggdG9rZW4...
          x-gitbook-description-html: <p>Tokens refreshed</p>
        "401":
          description: Invalid or expired refresh token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          x-gitbook-description-html: <p>Invalid or expired refresh token</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: Exchange refresh token for new access and refresh tokens.
                    marks: []
      x-gitbook-description-html: <p>Exchange refresh token for new access and refresh tokens.</p>
  /auth/logout:
    post:
      tags:
        - Auth
      summary: Logout
      description: Invalidate the provided refresh token.
      operationId: logout
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LogoutRequest"
            example:
              refresh_token: dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...
      responses:
        "200":
          description: Logged out successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
              example:
                message: Logged out successfully
          x-gitbook-description-html: <p>Logged out successfully</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: Invalidate the provided refresh token.
                    marks: []
      x-gitbook-description-html: <p>Invalidate the provided refresh token.</p>
  /auth/logout-all:
    post:
      tags:
        - Auth
      summary: Logout all sessions
      description: Invalidate all sessions for the current user.
      operationId: logoutAll
      responses:
        "200":
          description: All sessions logged out
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
              example:
                message: All sessions logged out successfully
          x-gitbook-description-html: <p>All sessions logged out</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: Invalidate all sessions for the current user.
                    marks: []
      x-gitbook-description-html: <p>Invalidate all sessions for the current user.</p>
  /auth/sessions:
    post:
      tags:
        - Auth
      summary: Get active sessions
      description: Retrieve all active sessions for the current user.
      operationId: getSessions
      responses:
        "200":
          description: List of active sessions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionsResponse"
              example:
                sessions:
                  - id: 550e8400-e29b-41d4-a716-446655440000
                    userAgent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)
                    lastAccessedAt: "2025-01-15T10:30:00.000Z"
                    createdAt: "2025-01-10T08:00:00.000Z"
          x-gitbook-description-html: <p>List of active sessions</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: Retrieve all active sessions for the current user.
                    marks: []
      x-gitbook-description-html: <p>Retrieve all active sessions for the current user.</p>
  /auth/revoke-session:
    post:
      tags:
        - Auth
      summary: Revoke session
      description: Revoke a specific session by ID.
      operationId: revokeSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RevokeSessionRequest"
            example:
              sessionId: 550e8400-e29b-41d4-a716-446655440000
      responses:
        "200":
          description: Session revoked
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
              example:
                message: Session revoked successfully
          x-gitbook-description-html: <p>Session revoked</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: Revoke a specific session by ID.
                    marks: []
      x-gitbook-description-html: <p>Revoke a specific session by ID.</p>
  /users/me:
    get:
      tags:
        - Users
      summary: Get current user
      description: Retrieve the current user's profile with organization details.
      operationId: getCurrentUser
      responses:
        "200":
          description: Current user profile
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserMeResponse"
              example:
                id: 550e8400-e29b-41d4-a716-446655440000
                email: john.doe@example.com
                firstName: John
                lastName: Doe
                phone: "+212612345678"
                isEmailVerified: true
                lastLoginAt: "2025-01-15T10:30:00.000Z"
                createdAt: "2025-01-10T08:00:00.000Z"
                updatedAt: "2025-01-15T10:30:00.000Z"
                organization:
                  id: 660e8400-e29b-41d4-a716-446655440001
                  name: Acme Corporation
                  slug: acme-corp
                  country: MA
                  type: enterprise
                  industry: Technology
                  plan: trial
                  size: 11-50
                  primaryUse: sales
                  ice: null
                  timezone: Africa/Casablanca
                  currency: MAD
                  status: active
                  createdAt: "2025-01-10T08:00:00.000Z"
                  updatedAt: "2025-01-10T08:00:00.000Z"
          x-gitbook-description-html: <p>Current user profile</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: >-
                      Retrieve the current user's profile with organization
                      details.
                    marks: []
      x-gitbook-description-html: <p>Retrieve the current user's profile with organization details.</p>
  /users:
    get:
      tags:
        - Users
      summary: List all users (Staff)
      description: Retrieve all users. Requires staff privileges.
      operationId: listUsers
      responses:
        "200":
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/UserResponse"
          x-gitbook-description-html: <p>List of users</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "403":
          description: Staff access required
          x-gitbook-description-html: <p>Staff access required</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: Retrieve all users. Requires staff privileges.
                    marks: []
      x-gitbook-description-html: <p>Retrieve all users. Requires staff privileges.</p>
  /contact:
    get:
      tags:
        - Contacts
      summary: List contacts
      description: >-
        Get all contacts with pagination. Searchable: firstName, lastName,
        fullName, primaryPhone, primaryEmail.
      operationId: listContacts
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: search
          in: query
          schema:
            type: string
        - name: sortBy
          in: query
          schema:
            type: string
            enum:
              - firstName
              - lastName
              - primaryPhone
              - primaryEmail
              - createdAt
        - name: sortOrder
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        "200":
          description: Paginated list of contacts
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactListResponse"
          x-gitbook-description-html: <p>Paginated list of contacts</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: >-
                      Get all contacts with pagination. Searchable: firstName,
                      lastName, fullName, primaryPhone, primaryEmail.
                    marks: []
      x-gitbook-description-html: >-
        <p>Get all contacts with pagination. Searchable: firstName, lastName,
        fullName, primaryPhone, primaryEmail.</p>
    post:
      tags:
        - Contacts
      summary: Create contact
      operationId: createContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateContactRequest"
      responses:
        "201":
          description: Contact created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactResponse"
          x-gitbook-description-html: <p>Contact created</p>
        "400":
          description: Invalid input
          x-gitbook-description-html: <p>Invalid input</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "409":
          description: Phone number already exists
          x-gitbook-description-html: <p>Phone number already exists</p>
  /contact/upsert:
    post:
      tags:
        - Contacts
      summary: Bulk upsert contacts
      description: Bulk upsert contacts. Existing contacts matched by phone number.
      operationId: upsertContacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpsertContactRequest"
      responses:
        "201":
          description: Contacts upserted
          x-gitbook-description-html: <p>Contacts upserted</p>
        "400":
          description: Invalid input
          x-gitbook-description-html: <p>Invalid input</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: >-
                      Bulk upsert contacts. Existing contacts matched by phone
                      number.
                    marks: []
      x-gitbook-description-html: <p>Bulk upsert contacts. Existing contacts matched by phone number.</p>
  /contact/{id}:
    get:
      tags:
        - Contacts
      summary: Get contact by ID
      description: Get contact with custom attributes.
      operationId: getContactById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Contact with attributes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactWithAttributesResponse"
          x-gitbook-description-html: <p>Contact with attributes</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Contact not found
          x-gitbook-description-html: <p>Contact not found</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: Get contact with custom attributes.
                    marks: []
      x-gitbook-description-html: <p>Get contact with custom attributes.</p>
    put:
      tags:
        - Contacts
      summary: Update contact
      operationId: updateContact
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateContactRequest"
      responses:
        "200":
          description: Contact updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactResponse"
          x-gitbook-description-html: <p>Contact updated</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Contact not found
          x-gitbook-description-html: <p>Contact not found</p>
    delete:
      tags:
        - Contacts
      summary: Delete contact (soft)
      operationId: deleteContact
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Contact deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactResponse"
          x-gitbook-description-html: <p>Contact deleted</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Contact not found
          x-gitbook-description-html: <p>Contact not found</p>
  /custom-attributes:
    get:
      tags:
        - Custom Attributes
      summary: List custom attributes
      operationId: listCustomAttributes
      responses:
        "200":
          description: List of custom attributes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/CustomAttributeResponse"
          x-gitbook-description-html: <p>List of custom attributes</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
    post:
      tags:
        - Custom Attributes
      summary: Create custom attribute
      operationId: createCustomAttribute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCustomAttributeRequest"
      responses:
        "201":
          description: Custom attribute created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomAttributeResponse"
          x-gitbook-description-html: <p>Custom attribute created</p>
        "400":
          description: Invalid input
          x-gitbook-description-html: <p>Invalid input</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
  /custom-attributes/{customAttributeId}:
    get:
      tags:
        - Custom Attributes
      summary: Get custom attribute
      operationId: getCustomAttributeById
      parameters:
        - name: customAttributeId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Custom attribute details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomAttributeResponse"
          x-gitbook-description-html: <p>Custom attribute details</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Custom attribute not found
          x-gitbook-description-html: <p>Custom attribute not found</p>
    put:
      tags:
        - Custom Attributes
      summary: Update custom attribute
      operationId: updateCustomAttribute
      parameters:
        - name: customAttributeId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateCustomAttributeRequest"
      responses:
        "200":
          description: Custom attribute updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomAttributeResponse"
          x-gitbook-description-html: <p>Custom attribute updated</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Custom attribute not found
          x-gitbook-description-html: <p>Custom attribute not found</p>
    delete:
      tags:
        - Custom Attributes
      summary: Delete custom attribute
      operationId: deleteCustomAttribute
      parameters:
        - name: customAttributeId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Custom attribute deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomAttributeResponse"
          x-gitbook-description-html: <p>Custom attribute deleted</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Custom attribute not found
          x-gitbook-description-html: <p>Custom attribute not found</p>
  /audience:
    get:
      tags:
        - Audiences
      summary: List audiences
      description: "Get all audiences with pagination. Searchable: name, description."
      operationId: listAudiences
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: search
          in: query
          schema:
            type: string
        - name: sortBy
          in: query
          schema:
            type: string
            enum:
              - name
              - createdAt
              - updatedAt
        - name: sortOrder
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        "200":
          description: Paginated list of audiences
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AudienceListResponse"
          x-gitbook-description-html: <p>Paginated list of audiences</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: >-
                      Get all audiences with pagination. Searchable: name,
                      description.
                    marks: []
      x-gitbook-description-html: "<p>Get all audiences with pagination. Searchable: name, description.</p>"
    post:
      tags:
        - Audiences
      summary: Create audience
      operationId: createAudience
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAudienceRequest"
      responses:
        "201":
          description: Audience created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AudienceResponse"
          x-gitbook-description-html: <p>Audience created</p>
        "400":
          description: Invalid input
          x-gitbook-description-html: <p>Invalid input</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
  /audience/{id}:
    get:
      tags:
        - Audiences
      summary: Get audience by ID
      operationId: getAudienceById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Audience details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AudienceResponse"
          x-gitbook-description-html: <p>Audience details</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Audience not found
          x-gitbook-description-html: <p>Audience not found</p>
    put:
      tags:
        - Audiences
      summary: Update audience
      operationId: updateAudience
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateAudienceRequest"
      responses:
        "200":
          description: Audience updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AudienceResponse"
          x-gitbook-description-html: <p>Audience updated</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Audience not found
          x-gitbook-description-html: <p>Audience not found</p>
    delete:
      tags:
        - Audiences
      summary: Delete audience
      operationId: deleteAudience
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Audience deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AudienceResponse"
          x-gitbook-description-html: <p>Audience deleted</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Audience not found
          x-gitbook-description-html: <p>Audience not found</p>
  /audience/{id}/add-contacts:
    post:
      tags:
        - Audiences
      summary: Add contacts to audience
      operationId: addContactsToAudience
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddContactsRequest"
      responses:
        "200":
          description: Contacts added
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uuid
          x-gitbook-description-html: <p>Contacts added</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Audience not found
          x-gitbook-description-html: <p>Audience not found</p>
  /audio-management/upload:
    post:
      tags:
        - Audio
      summary: Upload audio file
      description: Upload and process audio file for use in call flows.
      operationId: uploadAudio
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/UploadAudioRequest"
      responses:
        "201":
          description: Audio uploaded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AudioResponse"
          x-gitbook-description-html: <p>Audio uploaded</p>
        "400":
          description: Invalid file or data
          x-gitbook-description-html: <p>Invalid file or data</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: Upload and process audio file for use in call flows.
                    marks: []
      x-gitbook-description-html: <p>Upload and process audio file for use in call flows.</p>
  /audio-management/audios:
    get:
      tags:
        - Audio
      summary: List audio files
      description: "Get paginated list of audio files. Searchable: title, description, tags."
      operationId: listAudios
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: search
          in: query
          schema:
            type: string
        - name: sortBy
          in: query
          schema:
            type: string
            enum:
              - createdAt
              - title
              - durationSeconds
        - name: sortOrder
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - name: usageType
          in: query
          schema:
            $ref: "#/components/schemas/AudioUsageType"
      responses:
        "200":
          description: Paginated list of audio files
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AudioListResponse"
          x-gitbook-description-html: <p>Paginated list of audio files</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: >-
                      Get paginated list of audio files. Searchable: title,
                      description, tags.
                    marks: []
      x-gitbook-description-html: >-
        <p>Get paginated list of audio files. Searchable: title, description,
        tags.</p>
  /audio-management/audio/{id}:
    get:
      tags:
        - Audio
      summary: Stream audio file
      operationId: streamAudio
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Audio file stream
          content:
            audio/*:
              schema:
                type: string
                format: binary
          x-gitbook-description-html: <p>Audio file stream</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Audio not found
          x-gitbook-description-html: <p>Audio not found</p>
    put:
      tags:
        - Audio
      summary: Update audio metadata
      operationId: updateAudio
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateAudioRequest"
      responses:
        "200":
          description: Audio updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AudioResponse"
          x-gitbook-description-html: <p>Audio updated</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Audio not found
          x-gitbook-description-html: <p>Audio not found</p>
    delete:
      tags:
        - Audio
      summary: Delete audio file
      operationId: deleteAudio
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Audio deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
          x-gitbook-description-html: <p>Audio deleted</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Audio not found
          x-gitbook-description-html: <p>Audio not found</p>
  /audio-management/audio/{id}/metadata:
    get:
      tags:
        - Audio
      summary: Get audio metadata
      operationId: getAudioMetadata
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Audio metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AudioResponse"
          x-gitbook-description-html: <p>Audio metadata</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Audio not found
          x-gitbook-description-html: <p>Audio not found</p>
  /audio-management/audio/{id}/details:
    get:
      tags:
        - Audio
      summary: Get audio with relations
      operationId: getAudioDetails
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Audio with relations
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AudioWithRelationsResponse"
          x-gitbook-description-html: <p>Audio with relations</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Audio not found
          x-gitbook-description-html: <p>Audio not found</p>
  /audio-management/audio/{id}/playback-url:
    get:
      tags:
        - Audio
      summary: Get playback URL
      description: Generate temporary signed URL for audio playback.
      operationId: getAudioPlaybackUrl
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: expiresIn
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 86400
            default: 3600
          description: URL expiration in seconds
          x-gitbook-description-html: <p>URL expiration in seconds</p>
      responses:
        "200":
          description: Playback URL generated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlaybackUrlResponse"
          x-gitbook-description-html: <p>Playback URL generated</p>
        "400":
          description: Invalid expiresIn
          x-gitbook-description-html: <p>Invalid expiresIn</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Audio not found
          x-gitbook-description-html: <p>Audio not found</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: Generate temporary signed URL for audio playback.
                    marks: []
      x-gitbook-description-html: <p>Generate temporary signed URL for audio playback.</p>
  /audio-management/audios/usage/{usageType}:
    get:
      tags:
        - Audio
      summary: Get audio by usage type
      operationId: getAudiosByUsageType
      parameters:
        - name: usageType
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/AudioUsageType"
      responses:
        "200":
          description: List of audio files
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AudioResponse"
          x-gitbook-description-html: <p>List of audio files</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
  /dictionaries:
    get:
      tags:
        - Dictionaries
      summary: List dictionaries
      operationId: listDictionaries
      responses:
        "200":
          description: List of dictionaries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/DictionaryResponse"
          x-gitbook-description-html: <p>List of dictionaries</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
    post:
      tags:
        - Dictionaries
      summary: Create dictionary
      operationId: createDictionary
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDictionaryRequest"
      responses:
        "201":
          description: Dictionary created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DictionaryResponse"
          x-gitbook-description-html: <p>Dictionary created</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
  /dictionaries/{dictionaryId}:
    get:
      tags:
        - Dictionaries
      summary: Get dictionary
      operationId: getDictionaryById
      parameters:
        - name: dictionaryId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Dictionary details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DictionaryResponse"
          x-gitbook-description-html: <p>Dictionary details</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Dictionary not found
          x-gitbook-description-html: <p>Dictionary not found</p>
    delete:
      tags:
        - Dictionaries
      summary: Delete dictionary
      operationId: deleteDictionary
      parameters:
        - name: dictionaryId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Dictionary deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
          x-gitbook-description-html: <p>Dictionary deleted</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Dictionary not found
          x-gitbook-description-html: <p>Dictionary not found</p>
  /dictionaries/{dictionaryId}/entries:
    post:
      tags:
        - Dictionaries
      summary: Add dictionary entry
      operationId: addDictionaryEntry
      parameters:
        - name: dictionaryId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/AddEntryRequest"
      responses:
        "201":
          description: Entry added
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DictionaryEntryResponse"
          x-gitbook-description-html: <p>Entry added</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Dictionary not found
          x-gitbook-description-html: <p>Dictionary not found</p>
  /dictionaries/{dictionaryId}/entries/{key}:
    get:
      tags:
        - Dictionaries
      summary: Get dictionary entry
      operationId: getDictionaryEntry
      parameters:
        - name: dictionaryId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: key
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Entry details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DictionaryEntryResponse"
          x-gitbook-description-html: <p>Entry details</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Entry not found
          x-gitbook-description-html: <p>Entry not found</p>
    delete:
      tags:
        - Dictionaries
      summary: Remove dictionary entry
      operationId: removeDictionaryEntry
      parameters:
        - name: dictionaryId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: key
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Entry removed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
          x-gitbook-description-html: <p>Entry removed</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Entry not found
          x-gitbook-description-html: <p>Entry not found</p>
  /admin/dictionaries/system/{language}/entries:
    post:
      tags:
        - Dictionaries
      summary: Add system dictionary entry (Staff)
      operationId: addSystemDictionaryEntry
      parameters:
        - name: language
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/SoundLanguage"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/AddEntryRequest"
      responses:
        "201":
          description: Entry added
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DictionaryEntryResponse"
          x-gitbook-description-html: <p>Entry added</p>
        "400":
          description: Invalid language
          x-gitbook-description-html: <p>Invalid language</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "403":
          description: Staff access required
          x-gitbook-description-html: <p>Staff access required</p>
        "404":
          description: System dictionary not found
          x-gitbook-description-html: <p>System dictionary not found</p>
  /flows:
    get:
      tags:
        - Flows
      summary: List flows
      operationId: listFlows
      responses:
        "200":
          description: List of flows
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FlowDefinition"
          x-gitbook-description-html: <p>List of flows</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
    post:
      tags:
        - Flows
      summary: Create flow
      operationId: createFlow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateFlowInput"
      responses:
        "201":
          description: Flow created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlowDefinition"
          x-gitbook-description-html: <p>Flow created</p>
        "400":
          description: Invalid flow definition
          x-gitbook-description-html: <p>Invalid flow definition</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
  /flows/validate:
    post:
      tags:
        - Flows
      summary: Validate flow
      description: Validate a flow definition without saving.
      operationId: validateFlow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FlowDefinition"
      responses:
        "200":
          description: Validation result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidateFlowResponse"
          x-gitbook-description-html: <p>Validation result</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: Validate a flow definition without saving.
                    marks: []
      x-gitbook-description-html: <p>Validate a flow definition without saving.</p>
  /flows/execute:
    post:
      tags:
        - Flows
      summary: Execute flow
      description: Execute a flow (creates outbound call and runs flow).
      operationId: executeFlow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExecuteFlowRequest"
      responses:
        "200":
          description: Flow execution result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlowExecutionResult"
          x-gitbook-description-html: <p>Flow execution result</p>
        "400":
          description: Invalid request
          x-gitbook-description-html: <p>Invalid request</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Flow or contact not found
          x-gitbook-description-html: <p>Flow or contact not found</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: Execute a flow (creates outbound call and runs flow).
                    marks: []
      x-gitbook-description-html: <p>Execute a flow (creates outbound call and runs flow).</p>
  /flows/latest/{name}:
    get:
      tags:
        - Flows
      summary: Get latest flow by name
      operationId: getLatestFlowByName
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Flow definition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlowDefinition"
          x-gitbook-description-html: <p>Flow definition</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Flow not found
          x-gitbook-description-html: <p>Flow not found</p>
  /flows/{flowId}:
    get:
      tags:
        - Flows
      summary: Get flow by ID
      operationId: getFlowById
      parameters:
        - name: flowId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Flow definition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlowDefinition"
          x-gitbook-description-html: <p>Flow definition</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Flow not found
          x-gitbook-description-html: <p>Flow not found</p>
    put:
      tags:
        - Flows
      summary: Update flow
      operationId: updateFlow
      parameters:
        - name: flowId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateFlowInput"
      responses:
        "200":
          description: Flow updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlowDefinition"
          x-gitbook-description-html: <p>Flow updated</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Flow not found
          x-gitbook-description-html: <p>Flow not found</p>
    delete:
      tags:
        - Flows
      summary: Delete flow (soft)
      operationId: deleteFlow
      parameters:
        - name: flowId
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Flow deleted
          x-gitbook-description-html: <p>Flow deleted</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Flow not found
          x-gitbook-description-html: <p>Flow not found</p>
  /flows/{flowId}/permanent:
    delete:
      tags:
        - Flows
      summary: Delete flow permanently (Staff)
      operationId: hardDeleteFlow
      parameters:
        - name: flowId
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Flow permanently deleted
          x-gitbook-description-html: <p>Flow permanently deleted</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "403":
          description: Staff access required
          x-gitbook-description-html: <p>Staff access required</p>
        "404":
          description: Flow not found
          x-gitbook-description-html: <p>Flow not found</p>
  /call-requests:
    post:
      tags:
        - Call Requests
      summary: Request call
      description: Request an ad-hoc call with optional retry strategy.
      operationId: requestCall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RequestCallDto"
      responses:
        "202":
          description: Call request accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CallRequestResult"
          x-gitbook-description-html: <p>Call request accepted</p>
        "400":
          description: Invalid request
          x-gitbook-description-html: <p>Invalid request</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Flow or contact not found
          x-gitbook-description-html: <p>Flow or contact not found</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: Request an ad-hoc call with optional retry strategy.
                    marks: []
      x-gitbook-description-html: <p>Request an ad-hoc call with optional retry strategy.</p>
  /call-requests/{jobId}:
    delete:
      tags:
        - Call Requests
      summary: Cancel queued call
      description: Cancel a queued call. No-op if already executing or completed.
      operationId: cancelCallRequest
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Call cancelled
          x-gitbook-description-html: <p>Call cancelled</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: >-
                      Cancel a queued call. No-op if already executing or
                      completed.
                    marks: []
      x-gitbook-description-html: <p>Cancel a queued call. No-op if already executing or completed.</p>
  /call-report/{jobId}:
    get:
      tags:
        - Call Reports
      summary: Get call report
      description: >-
        Get full report for a call request job, including all attempts, events,
        and flow execution details.
      operationId: getCallReport
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Job report
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobReport"
          x-gitbook-description-html: <p>Job report</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Job not found
          x-gitbook-description-html: <p>Job not found</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: >-
                      Get full report for a call request job, including all
                      attempts, events, and flow execution details.
                    marks: []
      x-gitbook-description-html: >-
        <p>Get full report for a call request job, including all attempts,
        events, and flow execution details.</p>
  /programs:
    get:
      tags:
        - Programs
      summary: List programs
      operationId: listPrograms
      responses:
        "200":
          description: List of programs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ProgramResponse"
          x-gitbook-description-html: <p>List of programs</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
    post:
      tags:
        - Programs
      summary: Create program
      description: Create a new calling campaign program.
      operationId: createProgram
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateProgramRequest"
      responses:
        "201":
          description: Program created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProgramResponse"
          x-gitbook-description-html: <p>Program created</p>
        "400":
          description: Invalid request
          x-gitbook-description-html: <p>Invalid request</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: Create a new calling campaign program.
                    marks: []
      x-gitbook-description-html: <p>Create a new calling campaign program.</p>
  /programs/{id}:
    get:
      tags:
        - Programs
      summary: Get program
      operationId: getProgramById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Program details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProgramResponse"
          x-gitbook-description-html: <p>Program details</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Program not found
          x-gitbook-description-html: <p>Program not found</p>
    patch:
      tags:
        - Programs
      summary: Update program
      operationId: updateProgram
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateProgramRequest"
      responses:
        "200":
          description: Program updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProgramResponse"
          x-gitbook-description-html: <p>Program updated</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Program not found
          x-gitbook-description-html: <p>Program not found</p>
    delete:
      tags:
        - Programs
      summary: Delete program
      operationId: deleteProgram
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Program deleted
          x-gitbook-description-html: <p>Program deleted</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Program not found
          x-gitbook-description-html: <p>Program not found</p>
  /programs/{id}/launch:
    post:
      tags:
        - Programs
      summary: Launch program execution
      operationId: launchProgram
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "201":
          description: Execution launched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LaunchResponse"
          x-gitbook-description-html: <p>Execution launched</p>
        "400":
          description: Execution already running or audience empty
          x-gitbook-description-html: <p>Execution already running or audience empty</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Program not found
          x-gitbook-description-html: <p>Program not found</p>
  /programs/{id}/executions:
    get:
      tags:
        - Programs
      summary: List program executions
      operationId: listProgramExecutions
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: List of executions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ExecutionResponse"
          x-gitbook-description-html: <p>List of executions</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Program not found
          x-gitbook-description-html: <p>Program not found</p>
  /program-executions:
    get:
      tags:
        - Program Executions
      summary: List active executions
      description: >-
        List all active executions (running, scheduled, paused) for the
        organization.
      operationId: listActiveExecutions
      responses:
        "200":
          description: List of active executions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ExecutionResponse"
          x-gitbook-description-html: <p>List of active executions</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: >-
                      List all active executions (running, scheduled, paused)
                      for the organization.
                    marks: []
      x-gitbook-description-html: >-
        <p>List all active executions (running, scheduled, paused) for the
        organization.</p>
  /program-executions/{id}:
    get:
      tags:
        - Program Executions
      summary: Get execution
      operationId: getExecutionById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Execution details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecutionResponse"
          x-gitbook-description-html: <p>Execution details</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Execution not found
          x-gitbook-description-html: <p>Execution not found</p>
    delete:
      tags:
        - Program Executions
      summary: Cancel execution
      description: Cancel an execution. Remaining pending contacts are marked as skipped.
      operationId: cancelExecution
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Execution cancelled
          x-gitbook-description-html: <p>Execution cancelled</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Execution not found
          x-gitbook-description-html: <p>Execution not found</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: >-
                      Cancel an execution. Remaining pending contacts are marked
                      as skipped.
                    marks: []
      x-gitbook-description-html: >-
        <p>Cancel an execution. Remaining pending contacts are marked as
        skipped.</p>
  /program-executions/{id}/pause:
    patch:
      tags:
        - Program Executions
      summary: Pause execution
      description: Pause a running execution. Already-queued calls continue to completion.
      operationId: pauseExecution
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Execution paused
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecutionResponse"
          x-gitbook-description-html: <p>Execution paused</p>
        "400":
          description: Execution not in running state
          x-gitbook-description-html: <p>Execution not in running state</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Execution not found
          x-gitbook-description-html: <p>Execution not found</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: >-
                      Pause a running execution. Already-queued calls continue
                      to completion.
                    marks: []
      x-gitbook-description-html: >-
        <p>Pause a running execution. Already-queued calls continue to
        completion.</p>
  /program-executions/{id}/resume:
    patch:
      tags:
        - Program Executions
      summary: Resume execution
      description: Resume a paused execution.
      operationId: resumeExecution
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Execution resumed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecutionResponse"
          x-gitbook-description-html: <p>Execution resumed</p>
        "400":
          description: Execution not in paused state
          x-gitbook-description-html: <p>Execution not in paused state</p>
        "401":
          description: Unauthorized
          x-gitbook-description-html: <p>Unauthorized</p>
        "404":
          description: Execution not found
          x-gitbook-description-html: <p>Execution not found</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: Resume a paused execution.
                    marks: []
      x-gitbook-description-html: <p>Resume a paused execution.</p>
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key provided by GoMobile team. Request yours at https://docs.google.com/forms/d/1F6_7OIDNq8_lWgKPyP-DudF3dvBTl31X4dqVf5St2zE
      x-gitbook-description-html: <p>API key provided by GoMobile team. Request yours at https://docs.google.com/forms/d/1F6_7OIDNq8_lWgKPyP-DudF3dvBTl31X4dqVf5St2zE</p>
  schemas:
    OrgType:
      type: string
      enum:
        - government
        - enterprise
        - individual
        - education
        - ngo
      description: Organization type
      x-gitbook-description-html: <p>Organization type</p>
    OrgPlan:
      type: string
      enum:
        - trial
        - free
        - basic
        - advanced
        - enterprise
      description: Subscription plan
      x-gitbook-description-html: <p>Subscription plan</p>
    OrgSize:
      type: string
      enum:
        - 1-10
        - 11-50
        - 51-200
        - 500+
      description: Organization size
      x-gitbook-description-html: <p>Organization size</p>
    OrgPrimaryUse:
      type: string
      enum:
        - sales
        - support
        - market research
      description: Primary use case
      x-gitbook-description-html: <p>Primary use case</p>
    OrgStatus:
      type: string
      enum:
        - active
        - suspended
        - inactive
      description: Organization status
      x-gitbook-description-html: <p>Organization status</p>
    LoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 8
    RefreshTokenRequest:
      type: object
      required:
        - refresh_token
      properties:
        refresh_token:
          type: string
    LogoutRequest:
      type: object
      required:
        - refresh_token
      properties:
        refresh_token:
          type: string
    RevokeSessionRequest:
      type: object
      required:
        - sessionId
      properties:
        sessionId:
          type: string
          format: uuid
    AuthResponse:
      type: object
      properties:
        access_token:
          type: string
        refresh_token:
          type: string
    MessageResponse:
      type: object
      properties:
        message:
          type: string
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
    Session:
      type: object
      properties:
        id:
          type: string
          format: uuid
        userAgent:
          type: string
          nullable: true
        lastAccessedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
    SessionsResponse:
      type: object
      properties:
        sessions:
          type: array
          items:
            $ref: "#/components/schemas/Session"
    UpdateUserRequest:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        phone:
          type: string
          description: E.164 format
          x-gitbook-description-html: <p>E.164 format</p>
    UserResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        firstName:
          type: string
        lastName:
          type: string
        phone:
          type: string
          nullable: true
        isEmailVerified:
          type: boolean
        lastLoginAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    OrganizationSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        country:
          type: string
        type:
          $ref: "#/components/schemas/OrgType"
        industry:
          type: string
        plan:
          $ref: "#/components/schemas/OrgPlan"
        size:
          $ref: "#/components/schemas/OrgSize"
        primaryUse:
          $ref: "#/components/schemas/OrgPrimaryUse"
        ice:
          type: string
          nullable: true
        timezone:
          type: string
        currency:
          type: string
        status:
          $ref: "#/components/schemas/OrgStatus"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    UserMeResponse:
      allOf:
        - $ref: "#/components/schemas/UserResponse"
        - type: object
          properties:
            organization:
              $ref: "#/components/schemas/OrganizationSummary"
    Gender:
      type: string
      enum:
        - male
        - female
    CreateContactRequest:
      type: object
      required:
        - primaryPhone
      properties:
        firstName:
          type: string
        lastName:
          type: string
        fullName:
          type: string
        primaryEmail:
          type: string
          format: email
        primaryPhone:
          type: string
        address:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
        occupation:
          type: string
        preferredChannel:
          type: string
        customAttributes:
          type: object
        gender:
          $ref: "#/components/schemas/Gender"
        channels:
          type: array
          items:
            type: string
    UpdateContactRequest:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        fullName:
          type: string
        primaryEmail:
          type: string
          format: email
        primaryPhone:
          type: string
        address:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
        occupation:
          type: string
        preferredChannel:
          type: string
        customAttributes:
          type: object
        gender:
          $ref: "#/components/schemas/Gender"
        channels:
          type: array
          items:
            type: string
    UpsertContactRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/CreateContactRequest"
    ContactChannel:
      type: object
      properties:
        type:
          type: string
        value:
          type: string
        isPrimary:
          type: boolean
    ContactResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        organizationId:
          type: string
          format: uuid
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        fullName:
          type: string
          nullable: true
        primaryEmail:
          type: string
          nullable: true
        primaryPhone:
          type: string
        address:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
        zip:
          type: string
          nullable: true
        occupation:
          type: string
          nullable: true
        preferredChannel:
          type: string
          nullable: true
        gender:
          $ref: "#/components/schemas/Gender"
        channels:
          type: array
          items:
            $ref: "#/components/schemas/ContactChannel"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        deletedAt:
          type: string
          format: date-time
          nullable: true
    ContactCustomAttribute:
      type: object
      properties:
        name:
          type: string
        displayName:
          type: string
        description:
          type: string
          nullable: true
        type:
          type: string
        value: {}
        isLocked:
          type: boolean
    ContactWithAttributesResponse:
      allOf:
        - $ref: "#/components/schemas/ContactResponse"
        - type: object
          properties:
            customAttributes:
              type: array
              items:
                $ref: "#/components/schemas/ContactCustomAttribute"
    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        totalPages:
          type: integer
        hasNextPage:
          type: boolean
        hasPreviousPage:
          type: boolean
    ContactListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ContactResponse"
        meta:
          $ref: "#/components/schemas/PaginationMeta"
    CustomAttributeType:
      type: string
      enum:
        - text
        - number
        - boolean
        - date
        - phone_number
        - email
        - url
    CreateCustomAttributeRequest:
      type: object
      required:
        - displayName
        - type
      properties:
        displayName:
          type: string
        description:
          type: string
        type:
          $ref: "#/components/schemas/CustomAttributeType"
    UpdateCustomAttributeRequest:
      type: object
      properties:
        description:
          type: string
    CustomAttributeResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        organizationId:
          type: string
          format: uuid
        name:
          type: string
        displayName:
          type: string
        description:
          type: string
          nullable: true
        type:
          $ref: "#/components/schemas/CustomAttributeType"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CreateAudienceRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string
    UpdateAudienceRequest:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
    AddContactsRequest:
      type: object
      required:
        - contacts
      properties:
        contacts:
          type: array
          items:
            type: string
            format: uuid
    AudienceResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        organizationId:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        deletedAt:
          type: string
          format: date-time
          nullable: true
    AudienceListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/AudienceResponse"
        meta:
          $ref: "#/components/schemas/PaginationMeta"
    AudioUsageType:
      type: string
      enum:
        - welcome
        - goodbye
        - question
        - prompt
        - hold_music
        - notification
        - other
    UploadAudioRequest:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          format: binary
        title:
          type: string
        description:
          type: string
        usageType:
          $ref: "#/components/schemas/AudioUsageType"
        tags:
          type: array
          items:
            type: string
    UpdateAudioRequest:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        usageType:
          $ref: "#/components/schemas/AudioUsageType"
        tags:
          type: array
          items:
            type: string
    AudioFile:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        contentType:
          type: string
        fileSize:
          type: integer
        checksum:
          type: string
          nullable: true
    AudioResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        description:
          type: string
          nullable: true
        usageType:
          $ref: "#/components/schemas/AudioUsageType"
        tags:
          type: array
          items:
            type: string
          nullable: true
        durationSeconds:
          type: number
          nullable: true
        sampleRate:
          type: integer
          nullable: true
        channels:
          type: integer
          nullable: true
        bitDepth:
          type: integer
          nullable: true
        organizationId:
          type: string
          format: uuid
          nullable: true
        originalFileName:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        file:
          $ref: "#/components/schemas/AudioFile"
    AudioWithRelationsResponse:
      allOf:
        - $ref: "#/components/schemas/AudioResponse"
        - type: object
          properties:
            organization:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                name:
                  type: string
                slug:
                  type: string
    AudioListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/AudioResponse"
        meta:
          $ref: "#/components/schemas/PaginationMeta"
    PlaybackUrlResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        playbackUrl:
          type: string
        expiresIn:
          type: integer
        expiresAt:
          type: string
          format: date-time
    SoundLanguage:
      type: string
      enum:
        - ar
        - fr
    CreateDictionaryRequest:
      type: object
      required:
        - name
        - language
      properties:
        name:
          type: string
        description:
          type: string
        language:
          $ref: "#/components/schemas/SoundLanguage"
    AddEntryRequest:
      type: object
      required:
        - file
        - key
      properties:
        file:
          type: string
          format: binary
        key:
          type: string
    DictionaryResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        language:
          $ref: "#/components/schemas/SoundLanguage"
        organizationId:
          type: string
          format: uuid
          nullable: true
        isSystem:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    DictionaryEntryResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        dictionaryId:
          type: string
          format: uuid
        key:
          type: string
        audioId:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    NodeType:
      type: string
      enum:
        - dial
        - answer
        - hangup
        - play
        - record
        - dtmf
        - condition
        - set_variable
    FlowExecutionOutcome:
      type: string
      enum:
        - completed
        - user_hangup
        - failed
        - timeout
        - no_answer
        - busy
        - rejected
        - cancelled
    FlowNode:
      type: object
      required:
        - id
        - type
      properties:
        id:
          type: string
        type:
          $ref: "#/components/schemas/NodeType"
        label:
          type: string
        description:
          type: string
        config:
          type: object
        outputs:
          type: object
    FlowGraph:
      type: object
      required:
        - nodes
        - startNodeId
      properties:
        nodes:
          type: array
          items:
            $ref: "#/components/schemas/FlowNode"
        startNodeId:
          type: string
    FlowMetadata:
      type: object
      properties:
        tags:
          type: array
          items:
            type: string
        category:
          type: string
        author:
          type: string
        version:
          type: string
    VariableSchema:
      type: object
      additionalProperties:
        type: object
        properties:
          type:
            type: string
            enum:
              - string
              - number
              - boolean
          required:
            type: boolean
          defaultValue: {}
          description:
            type: string
    FlowDefinition:
      type: object
      properties:
        id:
          type: string
        organizationId:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        version:
          type: integer
        metadata:
          $ref: "#/components/schemas/FlowMetadata"
        graph:
          $ref: "#/components/schemas/FlowGraph"
        variableSchema:
          $ref: "#/components/schemas/VariableSchema"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CreateFlowInput:
      type: object
      required:
        - name
        - graph
      properties:
        name:
          type: string
        description:
          type: string
        graph:
          $ref: "#/components/schemas/FlowGraph"
        metadata:
          $ref: "#/components/schemas/FlowMetadata"
        variableSchema:
          $ref: "#/components/schemas/VariableSchema"
    UpdateFlowInput:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        graph:
          $ref: "#/components/schemas/FlowGraph"
        metadata:
          $ref: "#/components/schemas/FlowMetadata"
        variableSchema:
          $ref: "#/components/schemas/VariableSchema"
    ExecuteFlowRequest:
      type: object
      required:
        - flowId
        - contactId
        - fromPhone
      properties:
        flowId:
          type: string
        contactId:
          type: string
        fromPhone:
          type: string
        initialVariables:
          type: object
    CallSessionSnapshot:
      type: object
      properties:
        callId:
          type: string
        status:
          type: string
        direction:
          type: string
        createdAt:
          type: string
          format: date-time
        answeredAt:
          type: string
          format: date-time
        terminatedAt:
          type: string
          format: date-time
        durationMs:
          type: integer
    ExecutionTiming:
      type: object
      properties:
        startedAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
        durationMs:
          type: integer
        nodeExecutionCount:
          type: integer
    FlowExecutionErrorDetails:
      type: object
      properties:
        type:
          type: string
        message:
          type: string
        code:
          type: string
        nodeId:
          type: string
        stack:
          type: string
    FlowExecutionResult:
      type: object
      properties:
        callId:
          type: string
        flowId:
          type: string
        outcome:
          $ref: "#/components/schemas/FlowExecutionOutcome"
        outcomeReason:
          type: string
        finalVariables:
          type: object
        error:
          $ref: "#/components/schemas/FlowExecutionErrorDetails"
        sessionSnapshot:
          $ref: "#/components/schemas/CallSessionSnapshot"
        timing:
          $ref: "#/components/schemas/ExecutionTiming"
    ValidationError:
      type: object
      properties:
        field:
          type: string
        message:
          type: string
        code:
          type: string
    ValidateFlowResponse:
      type: object
      properties:
        valid:
          type: boolean
        errors:
          type: array
          items:
            $ref: "#/components/schemas/ValidationError"
    RetryStrategy:
      oneOf:
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - none
        - type: object
          required:
            - type
            - delay
            - maxRetries
          properties:
            type:
              type: string
              enum:
                - fixed-delay
            delay:
              type: integer
            maxRetries:
              type: integer
        - type: object
          required:
            - type
            - dates
          properties:
            type:
              type: string
              enum:
                - scheduled
            dates:
              type: array
              items:
                type: string
                format: date-time
    RequestCallDto:
      type: object
      required:
        - fromNumber
        - contactId
        - flowId
        - retry
      properties:
        fromNumber:
          type: string
        contactId:
          type: string
        flowId:
          type: string
        retry:
          $ref: "#/components/schemas/RetryStrategy"
        startAt:
          type: string
          format: date-time
    CallRequestResult:
      type: object
      properties:
        jobId:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - queued
    JobStatus:
      type: string
      enum:
        - queued
        - active
        - completed
        - failed
    CallDetails:
      type: object
      properties:
        status:
          type: string
        direction:
          type: string
          enum:
            - inbound
            - outbound
        from:
          type: string
        to:
          type: string
        createdAt:
          type: string
          format: date-time
        dialedAt:
          type: string
          format: date-time
        answeredAt:
          type: string
          format: date-time
        terminatedAt:
          type: string
          format: date-time
        durationMs:
          type: integer
    NodeExecutionPathEntry:
      type: object
      properties:
        nodeId:
          type: string
        nodeType:
          type: string
        nodeLabel:
          type: string
        outputPath:
          type: string
        timestamp:
          type: string
          format: date-time
    FlowExecutionDetails:
      type: object
      properties:
        flowId:
          type: string
        flowName:
          type: string
        flowVersion:
          type: integer
        executionPath:
          type: array
          items:
            $ref: "#/components/schemas/NodeExecutionPathEntry"
        finalVariables:
          type: object
        nodeExecutionCount:
          type: integer
        flowStartedAt:
          type: string
          format: date-time
        flowCompletedAt:
          type: string
          format: date-time
    CallEvent:
      type: object
      properties:
        type:
          type: string
        timestamp:
          type: string
          format: date-time
        data:
          type: object
    CallAttemptReport:
      type: object
      properties:
        callId:
          type: string
          format: uuid
        attempt:
          type: integer
        call:
          $ref: "#/components/schemas/CallDetails"
        outcome:
          type: string
        outcomeReason:
          type: string
        flowExecution:
          $ref: "#/components/schemas/FlowExecutionDetails"
        events:
          type: array
          items:
            $ref: "#/components/schemas/CallEvent"
    JobReport:
      type: object
      properties:
        jobId:
          type: string
          format: uuid
        status:
          $ref: "#/components/schemas/JobStatus"
        finalOutcome:
          type: string
        attempts:
          type: array
          items:
            $ref: "#/components/schemas/CallAttemptReport"
    ProgramStatus:
      type: string
      enum:
        - draft
        - active
        - archived
    ExecutionStatus:
      type: string
      enum:
        - scheduled
        - running
        - paused
        - completed
        - stopped
        - cancelled
    ProgramRetryStrategy:
      oneOf:
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - none
        - type: object
          required:
            - type
            - delayMinutes
            - maxRetries
          properties:
            type:
              type: string
              enum:
                - fixed_delay
            delayMinutes:
              type: integer
            maxRetries:
              type: integer
        - type: object
          required:
            - type
            - retryDates
          properties:
            type:
              type: string
              enum:
                - scheduled
            retryDates:
              type: array
              items:
                type: string
                format: date-time
    PauseWindowTime:
      type: object
      properties:
        hour:
          type: integer
          minimum: 0
          maximum: 23
        minute:
          type: integer
          minimum: 0
          maximum: 59
    PauseWindowItem:
      type: object
      properties:
        startAt:
          $ref: "#/components/schemas/PauseWindowTime"
        endAt:
          $ref: "#/components/schemas/PauseWindowTime"
    PauseWindowAdvancedItem:
      type: object
      properties:
        startAt:
          type: string
          format: date-time
        endAt:
          type: string
          format: date-time
    PauseWindows:
      type: object
      properties:
        sunday:
          type: array
          items:
            $ref: "#/components/schemas/PauseWindowItem"
        monday:
          type: array
          items:
            $ref: "#/components/schemas/PauseWindowItem"
        tuesday:
          type: array
          items:
            $ref: "#/components/schemas/PauseWindowItem"
        wednesday:
          type: array
          items:
            $ref: "#/components/schemas/PauseWindowItem"
        thursday:
          type: array
          items:
            $ref: "#/components/schemas/PauseWindowItem"
        friday:
          type: array
          items:
            $ref: "#/components/schemas/PauseWindowItem"
        saturday:
          type: array
          items:
            $ref: "#/components/schemas/PauseWindowItem"
        advanced:
          type: array
          items:
            $ref: "#/components/schemas/PauseWindowAdvancedItem"
    CreateProgramRequest:
      type: object
      required:
        - name
        - audienceId
        - flowId
        - startAt
        - didPool
        - retryStrategy
      properties:
        name:
          type: string
        audienceId:
          type: string
          format: uuid
        flowId:
          type: string
          format: uuid
        startAt:
          type: string
          format: date-time
        stopAt:
          type: string
          format: date-time
        didPool:
          type: array
          items:
            type: string
        retryStrategy:
          $ref: "#/components/schemas/ProgramRetryStrategy"
        pauseWindows:
          $ref: "#/components/schemas/PauseWindows"
    UpdateProgramRequest:
      type: object
      properties:
        name:
          type: string
        audienceId:
          type: string
          format: uuid
        flowId:
          type: string
          format: uuid
        startAt:
          type: string
          format: date-time
        stopAt:
          type: string
          format: date-time
        didPool:
          type: array
          items:
            type: string
        retryStrategy:
          $ref: "#/components/schemas/ProgramRetryStrategy"
        pauseWindows:
          $ref: "#/components/schemas/PauseWindows"
    ProgramResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        organizationId:
          type: string
          format: uuid
        audienceId:
          type: string
          format: uuid
        flowId:
          type: string
          format: uuid
        status:
          $ref: "#/components/schemas/ProgramStatus"
        startAt:
          type: string
          format: date-time
        stopAt:
          type: string
          format: date-time
          nullable: true
        didPool:
          type: array
          items:
            type: string
        retryStrategy:
          $ref: "#/components/schemas/ProgramRetryStrategy"
        pauseWindows:
          $ref: "#/components/schemas/PauseWindows"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ExecutionResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        programId:
          type: string
          format: uuid
        organizationId:
          type: string
          format: uuid
        audienceId:
          type: string
          format: uuid
        flowId:
          type: string
          format: uuid
        status:
          $ref: "#/components/schemas/ExecutionStatus"
        totalContacts:
          type: integer
        contactsCompleted:
          type: integer
        contactsFailed:
          type: integer
        contactsPending:
          type: integer
        contactsInProgress:
          type: integer
        scheduledStartAt:
          type: string
          format: date-time
        scheduledStopAt:
          type: string
          format: date-time
        actualStartAt:
          type: string
          format: date-time
        actualEndAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    LaunchResponse:
      type: object
      properties:
        executionId:
          type: string
          format: uuid
