openapi: 3.2.0
info:
  title: DialNexa Workflows API
  description: Public `/v1` REST API for the DialNexa voice AI platform.
  version: 1.0.0
servers:
- url: https://api.dialnexa.com
  description: DialNexa production API
security:
- bearer: []
tags:
- name: Workflows
paths:
  /v1/workflows:
    get:
      operationId: listWorkflows
      parameters:
      - name: sortOrder
        required: false
        in: query
        schema:
          enum:
          - ASC
          - DESC
          type: string
      - name: sortBy
        required: false
        in: query
        schema:
          example: createdAt
          type: string
      - name: limit
        required: false
        in: query
        schema:
          example: 20
          type: number
      - name: page
        required: false
        in: query
        schema:
          example: 1
          type: number
      responses:
        '200':
          description: Workflows fetched successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    example: 200
                  message:
                    type: string
                    example: Workflows fetched successfully
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: workflow_abc123
                        title:
                          type: string
                          example: Q3 Outreach Workflow
                        status:
                          type: string
                          enum:
                          - draft
                          - active
                          - paused
                          - completed
                          - cancelled
                          example: active
                        description:
                          type:
                          - string
                          - 'null'
                          example: Automated follow-up sequence
                        createdAt:
                          type: string
                          format: date-time
                        updatedAt:
                          type: string
                          format: date-time
                  meta:
                    type: object
                    properties:
                      totalItems:
                        type: number
                        example: 50
                      itemsPerPage:
                        type: number
                        example: 20
                      totalPages:
                        type: number
                        example: 3
                      currentPage:
                        type: number
                        example: 1
              examples:
                success:
                  summary: Successful response
                  value:
                    statusCode: 200
                    message: Workflows fetched successfully
                    data:
                    - id: workflow_abc123
                      title: Q3 Outreach Workflow
                      status: active
                      description: Automated follow-up sequence
                      createdAt: '2026-07-03T10:30:00.000Z'
                      updatedAt: '2026-07-03T10:45:00.000Z'
                    meta:
                      totalItems: 1
                      itemsPerPage: 20
                      totalPages: 1
                      currentPage: 1
        '400':
          description: Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 400 Bad Request
                  value:
                    statusCode: 400
                    message: Workflow validation failed
                    error: Bad Request
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 401 Unauthorized
                  value:
                    statusCode: 401
                    message: API key is missing or invalid
                    error: Unauthorized
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 500 Internal Server Error
                  value:
                    statusCode: 500
                    message: Internal server error
                    error: Internal Server Error
      security:
      - bearer: []
      summary: List Workflows
      tags:
      - Workflows
      description: Returns workflows for the authenticated workspace in a data and meta pagination envelope.
  /v1/workflows/{id}:
    get:
      operationId: getWorkflow
      parameters:
      - name: id
        required: true
        in: path
        description: Workflow ID
        schema:
          example: workflow_abc123
          type: string
      responses:
        '200':
          description: Workflow fetched successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    example: 200
                  message:
                    type: string
                    example: Workflow fetched successfully
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: workflow_abc123
                      title:
                        type: string
                        example: Q3 Outreach Workflow
                      status:
                        type: string
                        enum:
                        - draft
                        - active
                        - paused
                        - completed
                        - cancelled
                        example: active
                      description:
                        type:
                        - string
                        - 'null'
                        example: Automated follow-up sequence
                      createdAt:
                        type: string
                        format: date-time
                      updatedAt:
                        type: string
                        format: date-time
              examples:
                success:
                  summary: Successful response
                  value:
                    statusCode: 200
                    message: Workflow fetched successfully
                    data:
                      id: workflow_abc123
                      title: Q3 Outreach Workflow
                      status: active
                      description: Automated follow-up sequence
                      createdAt: '2026-07-03T10:30:00.000Z'
                      updatedAt: '2026-07-03T10:45:00.000Z'
        '400':
          description: Invalid workflow ID format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 400 Bad Request
                  value:
                    statusCode: 400
                    message: Workflow validation failed
                    error: Bad Request
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 401 Unauthorized
                  value:
                    statusCode: 401
                    message: API key is missing or invalid
                    error: Unauthorized
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 404 Not Found
                  value:
                    statusCode: 404
                    message: Workflow not found
                    error: Not Found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 500 Internal Server Error
                  value:
                    statusCode: 500
                    message: Internal server error
                    error: Internal Server Error
      security:
      - bearer: []
      summary: Get Workflow Details
      tags:
      - Workflows
      description: Returns one workflow and its current lifecycle state.
  /v1/workflows/{id}/status:
    patch:
      operationId: updateWorkflowStatus
      summary: Update Workflow Status
      description: Changes a workflow status. Use `activate` to start execution for all leads, `deactivate` to pause a currently active workflow, `pause` to pause a running workflow, or `resume` to continue a paused workflow.
      parameters:
      - name: id
        required: true
        in: path
        description: Workflow ID
        schema:
          example: workflow_abc123
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - action
              properties:
                action:
                  type: string
                  enum:
                  - activate
                  - deactivate
                  - pause
                  - resume
                  example: activate
                  description: The workflow status transition to apply.
            examples:
              activate:
                summary: Activate a workflow
                value:
                  action: activate
              deactivate:
                summary: Deactivate a workflow
                value:
                  action: deactivate
              pause:
                summary: Pause a workflow
                value:
                  action: pause
              resume:
                summary: Resume a workflow
                value:
                  action: resume
      responses:
        '200':
          description: Workflow status updated successfully.
          content:
            application/json:
              examples:
                success:
                  summary: Successful response
                  value:
                    statusCode: 200
                    message: Workflow activated successfully
                    data:
                      id: workflow_abc123
                      title: Q3 Outreach Workflow
                      status: active
                      description: Automated follow-up sequence
                      createdAt: '2026-07-03T10:30:00.000Z'
                      updatedAt: '2026-07-03T10:45:00.000Z'
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    example: 200
                  message:
                    type: string
                    example: Workflow activated successfully
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: workflow_abc123
                      title:
                        type: string
                        example: Q3 Outreach Workflow
                      status:
                        type: string
                        enum:
                        - draft
                        - active
                        - paused
                        - completed
                        - cancelled
                        example: active
                      description:
                        type:
                        - string
                        - 'null'
                        example: Automated follow-up sequence
                      createdAt:
                        type: string
                        format: date-time
                      updatedAt:
                        type: string
                        format: date-time
        '400':
          description: Invalid action, invalid workflow status, or workflow validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 400 Bad Request
                  value:
                    statusCode: 400
                    message: 'Invalid action. Must be one of: activate, deactivate, pause, resume'
                    error: Bad Request
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 401 Unauthorized
                  value:
                    statusCode: 401
                    message: API key is missing or invalid
                    error: Unauthorized
        '403':
          description: Forbidden - workflow does not belong to your organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 403 Forbidden
                  value:
                    statusCode: 403
                    message: You do not have permission to access this resource
                    error: Forbidden
        '404':
          description: Workflow not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 404 Not Found
                  value:
                    statusCode: 404
                    message: Workflow not found
                    error: Not Found
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 500 Internal Server Error
                  value:
                    statusCode: 500
                    message: Internal server error
                    error: Internal Server Error
      security:
      - bearer: []
      tags:
      - Workflows
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        message:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
          example: phone_number must be a valid E.164 phone number
        error:
          type: string
          example: Bad Request
      required:
      - statusCode
      - message
      - error
  securitySchemes:
    bearer:
      scheme: bearer
      type: http