openapi: 3.0.4
info:
  title: Evolution Foundation - CRM Service - Pipelines
  description: Management of contacts, conversations, inboxes, labels and macros
  version: 1.1.0
servers:
- url: https://api.evoai.app
  description: Production server
- url: http://localhost:3000
  description: Development server
  variables:
    port:
      default: '3000'
- url: '{customUrl}'
  description: Custom server
  variables:
    customUrl:
      default: https://your-instance.com
      description: Enter your server URL
paths:
  /api/v1/pipelines:
    get:
      operationId: list-pipelines
      summary: List all pipelines
      description: Get all active pipelines with stages, items, tasks info and services
      security:
      - userApiKey: []
      responses:
        '200':
          description: Pipelines retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                - message
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/pipeline'
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                        description: Response timestamp
                        example: '2024-01-15T10:30:00Z'
                  message:
                    type: string
                    description: Success message
                    example: Pipelines retrieved successfully
              example:
                success: true
                data:
                - id: 550e8400-e29b-41d4-a716-446655440000
                  name: Sales Pipeline Q1
                  account_id: 123e4567-e89b-12d3-a456-426614174000
                  created_by_id: 660e8400-e29b-41d4-a716-446655440001
                  description: Lead management and sales opportunity management.
                  pipeline_type: sales
                  visibility: private
                  is_active: true
                  custom_fields:
                    attributes: []
                  item_count: 0
                  conversations_count: 0
                  created_at: '2024-01-15T10:30:00Z'
                  updated_at: '2024-01-15T10:30:00Z'
                  stages:
                  - id: 770e8400-e29b-41d4-a716-446655440002
                    name: New Lead
                    pipeline_id: 550e8400-e29b-41d4-a716-446655440000
                    position: 1
                    color: '#3B82F6'
                    stage_type: 0
                    automation_rules:
                      description: New interested contacts
                    custom_fields:
                      attributes: []
                    created_at: '2024-01-15T10:30:00Z'
                    updated_at: '2024-01-15T10:30:00Z'
                    item_count: 0
                    items: []
                  - id: 880e8400-e29b-41d4-a716-446655440003
                    name: Qualification
                    pipeline_id: 550e8400-e29b-41d4-a716-446655440000
                    position: 2
                    color: '#F59E0B'
                    stage_type: 0
                    automation_rules:
                      description: Interest and fit verification
                    custom_fields:
                      attributes: []
                    created_at: '2024-01-15T10:30:00Z'
                    updated_at: '2024-01-15T10:30:00Z'
                    item_count: 0
                    items: []
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                message: Pipelines retrieved successfully
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                bad_request:
                  summary: Invalid request data
                  value:
                    success: false
                    error:
                      code: BAD_REQUEST
                      message: Invalid request data
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines
                      method: GET
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Unauthorized
                  value:
                    success: false
                    error:
                      code: UNAUTHORIZED
                      message: Unauthorized
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines
                      method: GET
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Forbidden
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: Forbidden
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines
                      method: GET
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_found:
                  summary: Resource not found
                  value:
                    success: false
                    error:
                      code: NOT_FOUND
                      message: Resource not found
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines
                      method: GET
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An internal server error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines
                      method: GET
    post:
      operationId: create-pipeline
      summary: Create a new pipeline
      description: Create a pipeline with optional custom stages or default stages based on pipeline type
      security:
      - userApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - pipeline
              properties:
                pipeline:
                  type: object
                  required:
                  - name
                  - pipeline_type
                  properties:
                    name:
                      type: string
                      example: Sales Pipeline Q1
                    description:
                      type: string
                      example: Q1 sales tracking pipeline
                    pipeline_type:
                      type: string
                      enum:
                      - sales
                      - support
                      - onboarding
                      - custom
                      - marketing
                      example: sales
                    visibility:
                      type: string
                      enum:
                      - private
                      - team
                      - public
                      default: private
                    custom_fields:
                      type: object
                      properties:
                        attributes:
                          type: array
                          items:
                            type: string
                          example:
                          - deal_value
                          - closing_probability
                stages:
                  type: array
                  description: Optional custom stages (if not provided, use create_default_stages)
                  items:
                    type: object
                    required:
                    - name
                    properties:
                      name:
                        type: string
                      color:
                        type: string
                        pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
                        default: '#60A5FA'
                      position:
                        type: integer
                      description:
                        type: string
                create_default_stages:
                  type: boolean
                  description: If true, creates default stages based on pipeline_type
                  default: false
      responses:
        '200':
          description: Pipeline created successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                - message
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/pipeline'
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                        description: Response timestamp
                        example: '2024-01-15T10:30:00Z'
                  message:
                    type: string
                    description: Success message
                    example: Pipeline created successfully
              example:
                success: true
                data:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  name: Sales Pipeline Q1
                  pipeline_type: sales
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                message: Pipeline created successfully
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                bad_request:
                  summary: Invalid request data
                  value:
                    success: false
                    error:
                      code: BAD_REQUEST
                      message: Invalid request data
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines
                      method: POST
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Unauthorized
                  value:
                    success: false
                    error:
                      code: UNAUTHORIZED
                      message: Unauthorized
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines
                      method: POST
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Forbidden
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: Forbidden
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines
                      method: POST
        '422':
          description: Unprocessable Entity (validation error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_error:
                  summary: Validation error
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Validation error
                      details:
                        name: Name is required
                        pipeline_type: Pipeline type is required
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines
                      method: POST
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An internal server error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines
                      method: POST
  /api/v1/pipelines/by_contact/{contact_id}:
    parameters:
    - name: contact_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Contact UUID
    get:
      operationId: get-pipelines-by-contact
      summary: Get pipelines containing a specific contact
      description: Returns all pipelines that have items associated with the specified contact
      security:
      - userApiKey: []
      responses:
        '200':
          description: Pipelines retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                - message
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/pipeline'
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                        description: Response timestamp
                        example: '2024-01-15T10:30:00Z'
                  message:
                    type: string
                    description: Success message
                    example: Pipelines retrieved successfully
              example:
                success: true
                data: []
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                message: Pipelines retrieved successfully
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                bad_request:
                  summary: Invalid request data
                  value:
                    success: false
                    error:
                      code: BAD_REQUEST
                      message: Invalid request data
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/by_contact/{contact_id}
                      method: GET
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Unauthorized
                  value:
                    success: false
                    error:
                      code: UNAUTHORIZED
                      message: Unauthorized
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/by_contact/{contact_id}
                      method: GET
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Forbidden
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: Forbidden
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/by_contact/{contact_id}
                      method: GET
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_found:
                  summary: Contact not found
                  value:
                    success: false
                    error:
                      code: NOT_FOUND
                      message: Contact not found
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/by_contact/{contact_id}
                      method: GET
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An internal server error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/by_contact/{contact_id}
                      method: GET
  /api/v1/pipelines/by_conversation/{conversation_id}:
    parameters:
    - name: conversation_id
      in: path
      required: true
      schema:
        type: string
      description: Conversation UUID or display_id
    get:
      operationId: get-pipelines-by-conversation
      summary: Get pipelines containing a specific conversation
      description: Returns all pipelines that have items associated with the specified conversation
      security:
      - userApiKey: []
      responses:
        '200':
          description: Pipelines retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                - message
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/pipeline'
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                        description: Response timestamp
                        example: '2024-01-15T10:30:00Z'
                  message:
                    type: string
                    description: Success message
                    example: Pipelines retrieved successfully
              example:
                success: true
                data: []
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                message: Pipelines retrieved successfully
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                bad_request:
                  summary: Invalid request data
                  value:
                    success: false
                    error:
                      code: BAD_REQUEST
                      message: Invalid request data
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/by_conversation/{conversation_id}
                      method: GET
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Unauthorized
                  value:
                    success: false
                    error:
                      code: UNAUTHORIZED
                      message: Unauthorized
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/by_conversation/{conversation_id}
                      method: GET
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Forbidden
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: Forbidden
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/by_conversation/{conversation_id}
                      method: GET
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_found:
                  summary: Conversation not found
                  value:
                    success: false
                    error:
                      code: NOT_FOUND
                      message: Conversation not found
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/by_conversation/{conversation_id}
                      method: GET
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An internal server error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/by_conversation/{conversation_id}
                      method: GET
  /api/v1/pipelines/stats:
    get:
      operationId: get-all-pipelines-stats
      summary: Get statistics for all pipelines
      description: Get aggregated statistics across all pipelines
      security:
      - userApiKey: []
      responses:
        '200':
          description: Pipeline statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                - message
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    description: Pipeline statistics data
                    properties:
                      total_pipelines:
                        type: integer
                        example: 5
                      active_pipelines:
                        type: integer
                        example: 4
                      inactive_pipelines:
                        type: integer
                        example: 1
                      total_items:
                        type: integer
                        example: 25
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                        description: Response timestamp
                        example: '2024-01-15T10:30:00Z'
                  message:
                    type: string
                    description: Success message
                    example: Pipeline statistics retrieved successfully
              example:
                success: true
                data:
                  total_pipelines: 5
                  active_pipelines: 4
                  inactive_pipelines: 1
                  total_items: 25
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                message: Pipeline statistics retrieved successfully
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                bad_request:
                  summary: Invalid request data
                  value:
                    success: false
                    error:
                      code: BAD_REQUEST
                      message: Invalid request data
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/stats
                      method: GET
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Unauthorized
                  value:
                    success: false
                    error:
                      code: UNAUTHORIZED
                      message: Unauthorized
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/stats
                      method: GET
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Forbidden
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: Forbidden
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/stats
                      method: GET
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An internal server error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/stats
                      method: GET
  /api/v1/pipelines/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Pipeline UUID
    get:
      operationId: get-pipeline
      summary: Get a single pipeline
      description: Get detailed information about a specific pipeline including stages, items, tasks
      security:
      - userApiKey: []
      responses:
        '200':
          description: Pipeline retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                - message
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/pipeline'
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                        description: Response timestamp
                        example: '2024-01-15T10:30:00Z'
                  message:
                    type: string
                    description: Success message
                    example: Pipeline retrieved successfully
              example:
                success: true
                data:
                  id: fb69bb0a-fe7c-4423-aa83-5995cf16cf26
                  name: Sales Manager
                  account_id: 37a1e39b-3579-47c2-bbb3-84829deae585
                  created_by_id: fc8ec60f-904f-4793-878d-e1534bcedee5
                  description: ''
                  pipeline_type: custom
                  visibility: private
                  is_active: true
                  custom_fields:
                    attributes: []
                  item_count: 0
                  conversations_count: 0
                  created_at: '2026-02-05T17:58:45Z'
                  updated_at: '2026-02-05T17:58:45Z'
                  stages:
                  - id: 358e6b22-b4f7-4c7a-b526-f6181f45d686
                    name: Completed
                    pipeline_id: fb69bb0a-fe7c-4423-aa83-5995cf16cf26
                    position: -3
                    color: '#10B981'
                    stage_type: 0
                    automation_rules:
                      description: Finalized
                    custom_fields:
                      attributes: []
                    created_at: '2026-02-05T17:58:45Z'
                    updated_at: '2026-02-05T17:58:45Z'
                    item_count: 0
                    items: []
                  - id: a0c4fd4f-5c05-4f92-b367-f576533103c0
                    name: In Progress
                    pipeline_id: fb69bb0a-fe7c-4423-aa83-5995cf16cf26
                    position: -2
                    color: '#F59E0B'
                    stage_type: 0
                    automation_rules:
                      description: In development
                    custom_fields:
                      attributes: []
                    created_at: '2026-02-05T17:58:45Z'
                    updated_at: '2026-02-05T17:58:45Z'
                    item_count: 0
                    items: []
                  - id: 19e823fa-b8aa-4417-8702-ad482b9c1a35
                    name: Start
                    pipeline_id: fb69bb0a-fe7c-4423-aa83-5995cf16cf26
                    position: -1
                    color: '#3B82F6'
                    stage_type: 0
                    automation_rules:
                      description: Starting point
                    custom_fields:
                      attributes:
                      - custumer_success
                    created_at: '2026-02-05T17:58:45Z'
                    updated_at: '2026-02-05T18:08:20Z'
                    item_count: 0
                    items: []
                meta:
                  timestamp: '2026-02-05T18:25:46Z'
                message: Pipeline retrieved successfully
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                bad_request:
                  summary: Invalid request data
                  value:
                    success: false
                    error:
                      code: BAD_REQUEST
                      message: Invalid request data
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}
                      method: GET
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Unauthorized
                  value:
                    success: false
                    error:
                      code: UNAUTHORIZED
                      message: Unauthorized
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}
                      method: GET
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Forbidden
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: Forbidden
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}
                      method: GET
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_found:
                  summary: Pipeline not found
                  value:
                    success: false
                    error:
                      code: NOT_FOUND
                      message: Pipeline not found
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}
                      method: GET
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An internal server error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}
                      method: GET
    patch:
      operationId: update-pipeline
      summary: Update a pipeline
      description: Update pipeline details
      security:
      - userApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - pipeline
              properties:
                pipeline:
                  type: object
                  properties:
                    name:
                      type: string
                    description:
                      type: string
                    pipeline_type:
                      type: string
                      enum:
                      - sales
                      - support
                      - onboarding
                      - custom
                      - marketing
                    visibility:
                      type: string
                      enum:
                      - private
                      - team
                      - public
                    custom_fields:
                      type: object
                      properties:
                        attributes:
                          type: array
                          items:
                            type: string
      responses:
        '200':
          description: Pipeline updated successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                - message
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/pipeline'
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                        description: Response timestamp
                        example: '2024-01-15T10:30:00Z'
                  message:
                    type: string
                    description: Success message
                    example: Pipeline updated successfully
              example:
                success: true
                data:
                  id: e8a01c36-f4d7-46fe-9883-6f2264cdf9bc
                  name: BUSSINESS
                  account_id: 37a1e39b-3579-47c2-bbb3-84829deae585
                  created_by_id: fc8ec60f-904f-4793-878d-e1534bcedee5
                  description: No conversation in this stage
                  pipeline_type: sales
                  visibility: private
                  is_active: true
                  custom_fields:
                    attributes: []
                  item_count: 0
                  conversations_count: 0
                  created_at: '2026-01-27T17:48:46Z'
                  updated_at: '2026-02-05T17:46:13Z'
                  stages:
                  - id: f8171680-ca2a-4373-8342-c0c18f795e65
                    name: New Lead
                    pipeline_id: e8a01c36-f4d7-46fe-9883-6f2264cdf9bc
                    position: 1
                    color: '#3B82F6'
                    stage_type: 0
                    automation_rules:
                      description: New interested contacts
                    custom_fields:
                      attributes: []
                    created_at: '2026-01-27T17:48:46Z'
                    updated_at: '2026-01-27T17:48:46Z'
                    item_count: 0
                  - id: f64f1897-b85f-4d3f-ac81-ad618beb3392
                    name: Qualification
                    pipeline_id: e8a01c36-f4d7-46fe-9883-6f2264cdf9bc
                    position: 2
                    color: '#F59E0B'
                    stage_type: 0
                    automation_rules:
                      description: Interest and fit verification
                    custom_fields:
                      attributes: []
                    created_at: '2026-01-27T17:48:46Z'
                    updated_at: '2026-01-27T17:48:46Z'
                    item_count: 0
                  - id: 753338e7-0d7c-4027-a9b1-427e35bbfa49
                    name: Proposal
                    pipeline_id: e8a01c36-f4d7-46fe-9883-6f2264cdf9bc
                    position: 3
                    color: '#8B5CF6'
                    stage_type: 0
                    automation_rules:
                      description: Proposal sent and negotiation
                    custom_fields:
                      attributes: []
                    created_at: '2026-01-27T17:48:46Z'
                    updated_at: '2026-01-27T17:48:46Z'
                    item_count: 0
                  - id: f6e993ef-1c29-4421-a3c6-33c95530b5a2
                    name: Closing
                    pipeline_id: e8a01c36-f4d7-46fe-9883-6f2264cdf9bc
                    position: 4
                    color: '#EC4899'
                    stage_type: 0
                    automation_rules:
                      description: Conclusion and onboarding
                    custom_fields:
                      attributes: []
                    created_at: '2026-01-27T17:48:46Z'
                    updated_at: '2026-01-27T17:49:04Z'
                    item_count: 0
                meta:
                  timestamp: '2026-02-05T17:46:15Z'
                message: Pipeline updated successfully
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                bad_request:
                  summary: Invalid request data
                  value:
                    success: false
                    error:
                      code: BAD_REQUEST
                      message: Invalid request data
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}
                      method: PATCH
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Unauthorized
                  value:
                    success: false
                    error:
                      code: UNAUTHORIZED
                      message: Unauthorized
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}
                      method: PATCH
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Forbidden
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: Forbidden
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}
                      method: PATCH
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_found:
                  summary: Pipeline not found
                  value:
                    success: false
                    error:
                      code: NOT_FOUND
                      message: Pipeline not found
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}
                      method: PATCH
        '422':
          description: Unprocessable Entity (validation error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_error:
                  summary: Validation error
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Validation error
                      details:
                        name: Name is required
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}
                      method: PATCH
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An internal server error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}
                      method: PATCH
    delete:
      operationId: delete-pipeline
      summary: Delete a pipeline
      description: Delete a pipeline (only if it has no active items)
      security:
      - userApiKey: []
      responses:
        '200':
          description: Pipeline deleted successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                - message
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    nullable: true
                    description: Null for delete operations
                    example: null
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                        description: Response timestamp
                        example: '2024-01-15T10:30:00Z'
                  message:
                    type: string
                    description: Success message
                    example: Pipeline deleted successfully
              example:
                success: true
                data: null
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                message: Pipeline deleted successfully
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                bad_request:
                  summary: Invalid request data
                  value:
                    success: false
                    error:
                      code: BAD_REQUEST
                      message: Invalid request data
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}
                      method: DELETE
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Unauthorized
                  value:
                    success: false
                    error:
                      code: UNAUTHORIZED
                      message: Unauthorized
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}
                      method: DELETE
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Forbidden
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: Forbidden
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}
                      method: DELETE
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_found:
                  summary: Pipeline not found
                  value:
                    success: false
                    error:
                      code: NOT_FOUND
                      message: Pipeline not found
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}
                      method: DELETE
        '422':
          description: Unprocessable Entity (validation error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_error:
                  summary: Cannot delete pipeline with active items
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Cannot delete pipeline with active items
                      details:
                        items: Pipeline has active items that must be removed first
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}
                      method: DELETE
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An internal server error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}
                      method: DELETE
  /api/v1/pipelines/{id}/archive:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    patch:
      operationId: archive-pipeline
      summary: Archive a pipeline
      description: Set pipeline as inactive
      security:
      - userApiKey: []
      responses:
        '200':
          description: Pipeline archived successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                - message
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/pipeline'
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                        description: Response timestamp
                        example: '2024-01-15T10:30:00Z'
                  message:
                    type: string
                    description: Success message
                    example: Pipeline archived successfully
              example:
                success: true
                data:
                  id: e8a01c36-f4d7-46fe-9883-6f2264cdf9bc
                  name: BUSSINESS
                  account_id: 37a1e39b-3579-47c2-bbb3-84829deae585
                  created_by_id: fc8ec60f-904f-4793-878d-e1534bcedee5
                  description: No conversation in this stage
                  pipeline_type: sales
                  visibility: private
                  is_active: false
                  custom_fields:
                    attributes: []
                  item_count: 0
                  conversations_count: 0
                  created_at: '2026-01-27T17:48:46Z'
                  updated_at: '2026-02-05T17:48:38Z'
                meta:
                  timestamp: '2026-02-05T17:49:34Z'
                message: Pipeline archived successfully
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                bad_request:
                  summary: Invalid request data
                  value:
                    success: false
                    error:
                      code: BAD_REQUEST
                      message: Invalid request data
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}/archive
                      method: PATCH
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Unauthorized
                  value:
                    success: false
                    error:
                      code: UNAUTHORIZED
                      message: Unauthorized
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}/archive
                      method: PATCH
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Forbidden
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: Forbidden
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}/archive
                      method: PATCH
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_found:
                  summary: Pipeline not found
                  value:
                    success: false
                    error:
                      code: NOT_FOUND
                      message: Pipeline not found
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}/archive
                      method: PATCH
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An internal server error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}/archive
                      method: PATCH
  /api/v1/pipelines/{id}/stats:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      operationId: get-pipeline-stats
      summary: Get pipeline statistics
      description: Get statistics for a specific pipeline including item counts by stage
      security:
      - userApiKey: []
      responses:
        '200':
          description: Pipeline statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                - message
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    description: Pipeline statistics data
                    properties:
                      total_items:
                        type: integer
                        example: 25
                      stage_counts:
                        type: object
                        additionalProperties:
                          type: integer
                        example:
                          550e8400-e29b-41d4-a716-446655440000: 10
                          660e8400-e29b-41d4-a716-446655440001: 15
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                        description: Response timestamp
                        example: '2024-01-15T10:30:00Z'
                  message:
                    type: string
                    description: Success message
                    example: Pipeline statistics retrieved successfully
              example:
                success: true
                data:
                  total_items: 25
                  stage_counts:
                    550e8400-e29b-41d4-a716-446655440000: 10
                    660e8400-e29b-41d4-a716-446655440001: 15
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                message: Pipeline statistics retrieved successfully
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                bad_request:
                  summary: Invalid request data
                  value:
                    success: false
                    error:
                      code: BAD_REQUEST
                      message: Invalid request data
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}/stats
                      method: GET
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Unauthorized
                  value:
                    success: false
                    error:
                      code: UNAUTHORIZED
                      message: Unauthorized
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}/stats
                      method: GET
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Forbidden
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: Forbidden
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}/stats
                      method: GET
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_found:
                  summary: Pipeline not found
                  value:
                    success: false
                    error:
                      code: NOT_FOUND
                      message: Pipeline not found
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}/stats
                      method: GET
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An internal server error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/pipelines/{id}/stats
                      method: GET
components:
  schemas:
    ErrorResponse:
      type: object
      required:
      - success
      - error
      - meta
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: Validation failed
            details:
              type: object
              additionalProperties: true
              nullable: true
        meta:
          type: object
          required:
          - timestamp
          - path
          - method
          properties:
            timestamp:
              type: string
              format: date-time
              example: '2024-01-15T10:30:00Z'
            path:
              type: string
              example: /public/api/v1/inboxes/{inbox_identifier}/contacts
            method:
              type: string
              example: POST
    contact:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
          nullable: true
        phone_number:
          type: string
          nullable: true
        account_id:
          type: string
          format: uuid
        custom_attributes:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    conversation:
      type: object
      properties:
        id:
          type: string
          format: uuid
        display_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - open
          - resolved
          - pending
          - snoozed
        contact_id:
          type: string
          format: uuid
        inbox_id:
          type: string
          format: uuid
        assignee_id:
          type: string
          format: uuid
          nullable: true
        team_id:
          type: string
          format: uuid
          nullable: true
        account_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        last_activity_at:
          type: string
          format: date-time
        contact:
          $ref: '#/components/schemas/contact'
        assignee:
          $ref: '#/components/schemas/user'
          nullable: true
        inbox:
          type: object
          properties:
            id:
              type: string
              format: uuid
            channel_id:
              type: string
              format: uuid
            name:
              type: string
            channel_type:
              type: string
            enable_auto_assignment:
              type: boolean
            greeting_enabled:
              type: boolean
            greeting_message:
              type: string
              nullable: true
            working_hours_enabled:
              type: boolean
            out_of_office_message:
              type: string
              nullable: true
            timezone:
              type: string
            enable_email_collect:
              type: boolean
            csat_survey_enabled:
              type: boolean
            allow_messages_after_resolved:
              type: boolean
            auto_assignment_config:
              type: object
              additionalProperties: true
            lock_to_single_conversation:
              type: boolean
            csat_config:
              type: object
              additionalProperties: true
            sender_name_type:
              type: string
            business_name:
              type: string
              nullable: true
            display_name:
              type: string
            default_conversation_status:
              type: string
              nullable: true
            avatar_url:
              type: string
            working_hours:
              type: array
              items:
                type: object
                properties:
                  day_of_week:
                    type: integer
                  closed_all_day:
                    type: boolean
                  open_hour:
                    type: integer
                    nullable: true
                  open_minutes:
                    type: integer
                    nullable: true
                  close_hour:
                    type: integer
                    nullable: true
                  close_minutes:
                    type: integer
                    nullable: true
                  open_all_day:
                    type: boolean
            created_at:
              type: integer
            updated_at:
              type: integer
            provider:
              type: string
    pipeline:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        pipeline_type:
          type: string
          enum:
          - sales
          - support
          - onboarding
          - custom
          - marketing
        visibility:
          type: string
          enum:
          - private
          - team
          - public
        is_active:
          type: boolean
        custom_fields:
          type: object
          properties:
            attributes:
              type: array
              items:
                type: string
        created_by_id:
          type: string
          format: uuid
        account_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        item_count:
          type: integer
          description: Total number of items in the pipeline
        conversations_count:
          type: integer
          description: Total number of conversations associated with the pipeline
        stages:
          type: array
          description: List of pipeline stages
          items:
            $ref: '#/components/schemas/pipeline_stage'
        pipeline_stages:
          type: array
          items:
            $ref: '#/components/schemas/pipeline_stage'
        pipeline_items:
          type: array
          items:
            $ref: '#/components/schemas/pipeline_item'
    pipeline_item:
      type: object
      properties:
        id:
          type: string
          format: uuid
        pipeline_id:
          type: string
          format: uuid
        pipeline_stage_id:
          type: string
          format: uuid
        conversation_id:
          type: string
          format: uuid
          nullable: true
        contact_id:
          type: string
          format: uuid
          nullable: true
        assigned_by_id:
          type: string
          format: uuid
          nullable: true
        custom_fields:
          type: object
          description: Custom field values including services, currency, etc.
        entered_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        is_lead:
          type: boolean
          description: True if contact-based (lead), false if conversation-based (deal)
        pipeline_stage:
          $ref: '#/components/schemas/pipeline_stage'
        conversation:
          $ref: '#/components/schemas/conversation'
          nullable: true
        contact:
          $ref: '#/components/schemas/contact'
          nullable: true
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/pipeline_task'
        pending_tasks_count:
          type: integer
        overdue_tasks_count:
          type: integer
        completed_tasks_count:
          type: integer
        services_total_value:
          type: number
          description: Sum of all service values
    pipeline_stage:
      type: object
      properties:
        id:
          type: string
          format: uuid
        pipeline_id:
          type: string
          format: uuid
        name:
          type: string
        color:
          type: string
          pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
        position:
          type: integer
        stage_type:
          type: integer
        automation_rules:
          type: object
        custom_fields:
          type: object
          properties:
            attributes:
              type: array
              items:
                type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        item_count:
          type: integer
          description: Number of items in this stage
        items:
          type: array
          description: List of pipeline items in this stage
          items:
            $ref: '#/components/schemas/pipeline_item'
    pipeline_task:
      type: object
      properties:
        id:
          type: string
          format: uuid
        pipeline_item_id:
          type: string
          format: uuid
        account_id:
          type: string
          format: uuid
        title:
          type: string
          maxLength: 255
        description:
          type: string
          nullable: true
        task_type:
          type: string
          enum:
          - call
          - email
          - meeting
          - follow_up
          - note
          - other
        status:
          type: string
          enum:
          - pending
          - completed
          - cancelled
          - overdue
        priority:
          type: string
          enum:
          - low
          - medium
          - high
          - urgent
        due_date:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        created_by_id:
          type: string
          format: uuid
        assigned_to_id:
          type: string
          format: uuid
          nullable: true
        parent_task_id:
          type: string
          format: uuid
          nullable: true
        position:
          type: integer
          description: Position among siblings
        depth:
          type: integer
          description: Hierarchy depth (0=root, 1=subtask, 2=sub-subtask)
        metadata:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        created_by:
          $ref: '#/components/schemas/user'
        assigned_to:
          $ref: '#/components/schemas/user'
          nullable: true
        parent_task:
          $ref: '#/components/schemas/pipeline_task'
          nullable: true
        subtasks:
          type: array
          items:
            $ref: '#/components/schemas/pipeline_task'
        subtask_count:
          type: integer
        overdue:
          type: boolean
        due_soon:
          type: boolean
        days_until_due:
          type: integer
          nullable: true
        hours_until_due:
          type: number
          nullable: true
    user:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
        avatar_url:
          type: string
          nullable: true
        available_name:
          type: string
          description: Display name for the user
  securitySchemes:
    userApiKey:
      type: apiKey
      in: header
      name: api_access_token
    ApiAccessToken:
      type: apiKey
      in: header
      name: api_access_token
      description: API access token for user authentication