openapi: 3.2.0
info:
  title: CustomerOS Flows API
  version: 1.0.0
  description: API for managing customer engagement flows and sequences
servers:
- url: https://api.customeros.ai/flow/{version}
  variables:
    version:
      default: v1
tags:
- name: Flows
paths:
  /flows:
    get:
      summary: List all flows
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowList'
      tags:
      - Flows
    post:
      summary: Create a new flow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlowCreate'
      responses:
        '201':
          description: Successfully created flow
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Flow'
      tags:
      - Flows
  /flows/{flow_id}:
    get:
      summary: Get details of a specific flow
      parameters:
      - $ref: '#/components/parameters/flow_id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Flow'
      tags:
      - Flows
    patch:
      summary: Update details of a specific flow
      parameters:
      - $ref: '#/components/parameters/flow_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlowUpdate'
      responses:
        '200':
          description: Successfully updated flow
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Flow'
      tags:
      - Flows
    delete:
      summary: Delete a specific flow
      parameters:
      - $ref: '#/components/parameters/flow_id'
      responses:
        '204':
          description: Successfully deleted flow
      tags:
      - Flows
  /flows/{flow_id}/enable:
    get:
      summary: Enable a flow
      parameters:
      - $ref: '#/components/parameters/flow_id'
      responses:
        '200':
          description: Successfully enabled flow
      tags:
      - Flows
  /flows/{flow_id}/disable:
    get:
      summary: Disable a flow
      parameters:
      - $ref: '#/components/parameters/flow_id'
      responses:
        '200':
          description: Successfully disabled flow
      tags:
      - Flows
  /flows/{flow_id}/stats:
    get:
      summary: Get stats for a flow
      parameters:
      - $ref: '#/components/parameters/flow_id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
      tags:
      - Flows
  /flows/{flow_id}/sequences:
    get:
      summary: List all sequences
      parameters:
      - $ref: '#/components/parameters/flow_id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SequenceList'
      tags:
      - Flows
    post:
      summary: Create new sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SequenceCreate'
      responses:
        '201':
          description: Successfully created sequence
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sequence'
      tags:
      - Flows
  /flows/{flow_id}/sequences/{sequence_id}:
    get:
      summary: Get details of a specific sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      - $ref: '#/components/parameters/sequence_id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sequence'
      tags:
      - Flows
    patch:
      summary: Update details of a specific sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      - $ref: '#/components/parameters/sequence_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SequenceUpdate'
      responses:
        '200':
          description: Successfully updated sequence
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sequence'
      tags:
      - Flows
    delete:
      summary: Delete a sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      - $ref: '#/components/parameters/sequence_id'
      responses:
        '204':
          description: Successfully deleted sequence
      tags:
      - Flows
  /flows/{flow_id}/sequences/{sequence_id}/enable:
    post:
      summary: Enable a sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      - $ref: '#/components/parameters/sequence_id'
      responses:
        '200':
          description: Successfully enabled sequence
      tags:
      - Flows
  /flows/{flow_id}/sequences/{sequence_id}/disable:
    post:
      summary: Disable a sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      - $ref: '#/components/parameters/sequence_id'
      responses:
        '200':
          description: Successfully disabled sequence
      tags:
      - Flows
  /flows/{flow_id}/sequences/{sequence_id}/stats:
    get:
      summary: Get statistics for a specific sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      - $ref: '#/components/parameters/sequence_id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
      tags:
      - Flows
  /flows/{flow_id}/schedule:
    get:
      summary: Get details of a specific sequence schedule
      parameters:
      - $ref: '#/components/parameters/flow_id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
      tags:
      - Flows
    put:
      summary: Update details of a specific sequence schedule
      parameters:
      - $ref: '#/components/parameters/flow_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleUpdate'
      responses:
        '200':
          description: Successfully updated schedule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
      tags:
      - Flows
    delete:
      summary: Delete details of a specific sequence schedule
      parameters:
      - $ref: '#/components/parameters/flow_id'
      responses:
        '204':
          description: Successfully deleted schedule
      tags:
      - Flows
  /flows/{flow_id}/config:
    get:
      summary: Get details of a specific sequence configuration
      parameters:
      - $ref: '#/components/parameters/flow_id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Config'
      tags:
      - Flows
    put:
      summary: Update details of a specific sequence configuration
      parameters:
      - $ref: '#/components/parameters/flow_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigUpdate'
      responses:
        '200':
          description: Successfully updated configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Config'
      tags:
      - Flows
    delete:
      summary: Delete details of a specific sequence configuration
      parameters:
      - $ref: '#/components/parameters/flow_id'
      responses:
        '204':
          description: Successfully deleted configuration
      tags:
      - Flows
  /flows/{flow_id}/sequences/{sequence_id}/steps:
    get:
      summary: List all steps for a sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      - $ref: '#/components/parameters/sequence_id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StepList'
      tags:
      - Flows
    post:
      summary: Add a step to a sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      - $ref: '#/components/parameters/sequence_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StepCreate'
      responses:
        '201':
          description: Successfully created step
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Step'
      tags:
      - Flows
  /flows/{flow_id}/sequences/{sequence_id}/steps/{step_id}:
    get:
      summary: List details for a step in a sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      - $ref: '#/components/parameters/sequence_id'
      - $ref: '#/components/parameters/step_id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Step'
      tags:
      - Flows
    put:
      summary: Update a step in a sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      - $ref: '#/components/parameters/sequence_id'
      - $ref: '#/components/parameters/step_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StepUpdate'
      responses:
        '200':
          description: Successfully updated step
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Step'
      tags:
      - Flows
    delete:
      summary: Delete a step in a sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      - $ref: '#/components/parameters/sequence_id'
      - $ref: '#/components/parameters/step_id'
      responses:
        '204':
          description: Successfully deleted step
      tags:
      - Flows
  /flows/{flow_id}/senders:
    get:
      summary: List all senders for a sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SenderList'
      tags:
      - Flows
    post:
      summary: Add a sender to a sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SenderCreate'
      responses:
        '201':
          description: Successfully created sender
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sender'
      tags:
      - Flows
  /flows/{flow_id}/senders/{sender_id}:
    delete:
      summary: Remove sender from a sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      - $ref: '#/components/parameters/sender_id'
      responses:
        '204':
          description: Successfully removed sender
      tags:
      - Flows
  /flows/{flow_id}/sequences/{sequence_id}/contacts:
    get:
      summary: List all contacts for a sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      - $ref: '#/components/parameters/sequence_id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
      tags:
      - Flows
    post:
      summary: Add contacts to a sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      - $ref: '#/components/parameters/sequence_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreate'
      responses:
        '201':
          description: Successfully added contacts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
      tags:
      - Flows
  /flows/{flow_id}/sequences/{sequence_id}/contacts/{contact_id}:
    get:
      summary: Get details of a specific contact in a sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      - $ref: '#/components/parameters/sequence_id'
      - $ref: '#/components/parameters/contact_id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
      tags:
      - Flows
    delete:
      summary: Remove a contact from a sequence
      parameters:
      - $ref: '#/components/parameters/flow_id'
      - $ref: '#/components/parameters/sequence_id'
      - $ref: '#/components/parameters/contact_id'
      responses:
        '204':
          description: Successfully removed contact
      tags:
      - Flows
components:
  parameters:
    sender_id:
      name: sender_id
      in: path
      required: true
      schema:
        type: string
    step_id:
      name: step_id
      in: path
      required: true
      schema:
        type: string
    flow_id:
      name: flow_id
      in: path
      required: true
      schema:
        type: string
    contact_id:
      name: contact_id
      in: path
      required: true
      schema:
        type: string
    sequence_id:
      name: sequence_id
      in: path
      required: true
      schema:
        type: string
  schemas:
    Flow:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - active
          - draft
        sequenceCount:
          type: integer
    Sender:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
        replyTo:
          type: string
        bcc:
          type: string
        status:
          type: string
          enum:
          - enabled
          - disabled
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        dailySendLimit:
          type: integer
        warmingStatus:
          type: string
          enum:
          - build
          - maintain
        emailSignature:
          type: object
          properties:
            enabled:
              type: boolean
            content:
              type: string
    ScheduleUpdate:
      type: object
      properties:
        schedule:
          $ref: '#/components/schemas/Schedule/properties/schedule'
    FlowCreate:
      type: object
      required:
      - name
      - status
      properties:
        name:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
          - active
          - draft
    Step:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - email
          - linkedin
          - manual
        order:
          type: integer
        status:
          type: string
          enum:
          - enabled
          - disabled
        details:
          oneOf:
          - $ref: '#/components/schemas/EmailStepDetails'
          - $ref: '#/components/schemas/LinkedInStepDetails'
          - $ref: '#/components/schemas/ManualStepDetails'
        waitTime:
          type: object
          properties:
            duration:
              type: integer
            unit:
              type: string
              enum:
              - minutes
              - hours
              - days
    SenderCreate:
      type: object
      required:
      - name
      - email
      properties:
        name:
          type: string
        email:
          type: string
        replyTo:
          type: string
        bcc:
          type: string
        status:
          type: string
          enum:
          - enabled
          - disabled
        dailySendLimit:
          type: integer
        warmingStatus:
          type: string
          enum:
          - build
          - maintain
        emailSignature:
          type: object
          properties:
            enabled:
              type: boolean
            content:
              type: string
    SequenceList:
      type: object
      properties:
        sequences:
          type: array
          items:
            $ref: '#/components/schemas/Sequence'
        pagination:
          $ref: '#/components/schemas/Pagination'
    SequenceCreate:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
          - enabled
          - disabled
        personas:
          type: array
          items:
            type: string
    Pagination:
      type: object
      properties:
        totalCount:
          type: integer
        page:
          type: integer
        perPage:
          type: integer
        totalPages:
          type: integer
    Sequence:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - enabled
          - disabled
        personas:
          type: array
          items:
            type: string
        stepCount:
          type: integer
    ManualStepDetails:
      type: object
      properties:
        title:
          type: string
        body:
          type: string
    ContactCreate:
      type: object
      required:
      - email
      properties:
        email:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        company:
          type: string
        status:
          type: string
          enum:
          - active
          - paused
    StepCreate:
      type: object
      required:
      - type
      - order
      - details
      - waitTime
      properties:
        type:
          type: string
          enum:
          - email
          - linkedin
          - manual
        order:
          type: integer
        status:
          type: string
          enum:
          - enabled
          - disabled
        details:
          oneOf:
          - $ref: '#/components/schemas/EmailStepDetails'
          - $ref: '#/components/schemas/LinkedInStepDetails'
          - $ref: '#/components/schemas/ManualStepDetails'
        waitTime:
          $ref: '#/components/schemas/Step/properties/waitTime'
    ConfigUpdate:
      type: object
      properties:
        config:
          $ref: '#/components/schemas/Config/properties/config'
    Contact:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        company:
          type: string
        status:
          type: string
          enum:
          - active
          - paused
          - completed
          - unsubscribed
        currentStep:
          type: integer
        addedAt:
          type: string
          format: date-time
        lastUpdated:
          type: string
          format: date-time
    SequenceUpdate:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
          - enabled
          - disabled
        personas:
          type: array
          items:
            type: string
    Schedule:
      type: object
      properties:
        flowId:
          type: string
        schedule:
          type: object
          properties:
            activeDays:
              type: array
              items:
                type: string
                enum:
                - monday
                - tuesday
                - wednesday
                - thursday
                - friday
                - saturday
                - sunday
            activeTimeWindow:
              type: object
              properties:
                start:
                  type: string
                  format: time
                end:
                  type: string
                  format: time
            pauseOnHolidays:
              type: boolean
            respectRecipientTimezone:
              type: boolean
            rules:
              type: object
              properties:
                minutesDelayBetweenEmails:
                  type: integer
            limits:
              type: object
              properties:
                emailsPerMailboxPerHour:
                  type: integer
                emailsPerMailboxPerDay:
                  type: integer
        lastUpdated:
          type: string
          format: date-time
    FlowUpdate:
      type: object
      properties:
        name:
          type: string
        status:
          type: string
          enum:
          - active
          - draft
    Config:
      type: object
      properties:
        flowId:
          type: string
        config:
          type: object
          properties:
            optOut:
              type: object
              properties:
                enabled:
                  type: boolean
                text:
                  type: string
            analytics:
              type: object
              properties:
                trackEmailOpens:
                  type: boolean
                trackLinkClicks:
                  type: object
                  properties:
                    enabled:
                      type: boolean
                    useCustomDomain:
                      type: boolean
                    customDomain:
                      type: string
        lastUpdated:
          type: string
          format: date-time
    SenderList:
      type: object
      properties:
        flowId:
          type: string
        senders:
          type: array
          items:
            $ref: '#/components/schemas/Sender'
        pagination:
          $ref: '#/components/schemas/Pagination'
    FlowList:
      type: object
      properties:
        flows:
          type: array
          items:
            $ref: '#/components/schemas/Flow'
        pagination:
          $ref: '#/components/schemas/Pagination'
    ContactList:
      type: object
      properties:
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        pagination:
          $ref: '#/components/schemas/Pagination'
    LinkedInStepDetails:
      type: object
      properties:
        actionType:
          type: string
          enum:
          - connection request
          - message
        message:
          type: string
        linkedinUrl:
          type: string
    StepUpdate:
      type: object
      properties:
        type:
          type: string
          enum:
          - email
          - linkedin
          - manual
        order:
          type: integer
        status:
          type: string
          enum:
          - enabled
          - disabled
        details:
          oneOf:
          - $ref: '#/components/schemas/EmailStepDetails'
          - $ref: '#/components/schemas/LinkedInStepDetails'
          - $ref: '#/components/schemas/ManualStepDetails'
        waitTime:
          $ref: '#/components/schemas/Step/properties/waitTime'
    StepList:
      type: object
      properties:
        sequenceId:
          type: string
        sequenceName:
          type: string
        steps:
          type: array
          items:
            $ref: '#/components/schemas/Step'
    EmailStepDetails:
      type: object
      properties:
        subject:
          type: string
        body:
          type: string