openapi: 3.2.0
info:
  title: Webex Contact Center Flows API
  version: 1.0.0
  description: The Webex Contact Center APIs allow developers to deeply integrate, configure, and manage cloud-based contact center solutions. These APIs cover agent lifecycle management, queue and routing configuration, customer journey tracking, and access to real-time and historical analytics. Use cases include embedding agent controls in custom UIs, automating workforce management, integrating with CRM and ticketing systems, and building custom reporting dashboards. The APIs empower organizations to deliver personalized, efficient customer experiences and optimize contact center operations.
  x-provenance:
    method: harvested
    authored_by: Cisco Webex
    harvested_by: API Evangelist
    harvested_on: '2026-08-19'
    first_party: true
    note: Published by Cisco. Retrieved unmodified except for this x-provenance block.
    provider_published: true
  x-evidence:
  - type: source
    url: https://github.com/webex/webex-openapi-specs/blob/main/public-spec/webex-contact-center.json
  - type: raw
    url: https://raw.githubusercontent.com/webex/webex-openapi-specs/main/public-spec/webex-contact-center.json
tags:
- name: Flows
paths:
  /{orgId}/project/{projectId}/flows:
    get:
      tags:
      - Flows
      summary: List Flows or Subflows
      description: 'Returns a list of flows in response. Channel-based filtering can be applied with the `searchBy` query parameter (for example, `channelType|telephony`, `channelType|workItem`, `channelType|customMessaging`, `channelType|genericAction`). Channel visibility may be constrained by organization feature flags.


        Scope: `cjp:config_read`. Roles: [`Organizational Full Admin`, `Supervisor`, `Contact Center Service Admin`, `User Admin`]'
      operationId: findFlowsUsingGET
      parameters:
      - name: flowType
        in: query
        description: Either of 'FLOW' or 'SUBFLOW'.
        schema:
          type: string
          default: FLOW
        example: FLOW
      - name: ids
        in: query
        description: Filters results based on a comma-separated list of flow IDs. If provided, only flows with those IDs will be fetched in the response.
        style: form
        schema:
          type: array
          items:
            type: string
        example:
        - 668e4b2d928d471e41da03d1
        - 668e3ee2928d471e41da03cb
      - name: orgId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
        example: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
      - name: page
        in: query
        description: Defines the number of the displayed page. The page number starts from 0.
        schema:
          type: integer
          format: int32
          default: 0
        example: 0
      - name: partialNameSearch
        in: query
        description: Performs a partial string match on the name of the flow. If the flow name contains the given string it will be fetched in the response.
        schema:
          type: string
        example: flow1
      - name: searchBy
        in: query
        description: Filter expression in the format `<field>|<value>`. Supports searching by `channelType` (for example, `channelType|telephony`, `channelType|workItem`, `channelType|customMessaging`, `channelType|genericAction`).
        schema:
          type: string
        example: channelType|customMessaging
      - name: projectId
        in: path
        description: 'Project ID. System generated value which is the same across orgs and environments. Always use: 5e5c9ad6d61f870d6d778c1b.'
        required: true
        schema:
          type: string
        example: 5e5c9ad6d61f870d6d778c1b
      - name: size
        in: query
        description: Defines the number of items to be displayed on a page. If the number specified is more than allowed max page size, the API will automatically adjust the page size to the max page size.
        schema:
          type: integer
          format: int32
          default: 10
        example: 10
      - name: includePagination
        in: query
        description: If set to true then a different paginated response object containing the page metadata (currentPage, totalRecords, pageSize, totalPages) will be returned. The flow objects will be in an array named "data".
        required: false
        schema:
          type: boolean
          default: false
        example: false
      - name: isValidation
        in: query
        description: If true, validates the existence of flows by ID regardless of the caller's RBAC access. Intended for internal Task Management use cases.
        required: false
        schema:
          type: boolean
          default: false
        example: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BasicFlow'
                example:
                - id: 65c28d9db2a2375974066579
                  name: TestFlow
                  flowType: FLOW
                  status: Draft
                  orgId: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
                  version: 1
        '400':
          description: Bad request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
        '500':
          description: Internal Server Error
          content: {}
  /{orgId}/project/{projectId}/flows:search:
    get:
      tags:
      - Flows
      summary: Search Flows
      description: 'Returns a list of flows in response. The search is case-sensitive.


        Scope: `cjp:config_read`. Roles: [`Organizational Full Admin`, `Supervisor`, `Contact Center Service Admin`, `User Admin`]'
      operationId: searchFlows
      parameters:
      - name: orgId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
        example: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
      - name: projectId
        in: path
        description: 'Project ID. System generated value which is the same across orgs and environments. Always use: 5e5c9ad6d61f870d6d778c1b.'
        required: true
        schema:
          type: string
        example: 5e5c9ad6d61f870d6d778c1b
      - name: query
        in: query
        description: Searches for flows with the given query. The search is case-sensitive.
        required: true
        schema:
          type: string
        example: flow1
      - name: flowType
        in: query
        description: Either of 'FLOW' or 'SUBFLOW' or 'ALL'. Default value is 'ALL'.
        required: false
        schema:
          type: string
          default: ALL
        example: FLOW
      - name: page
        in: query
        description: Defines the number of the displayed page. The page number starts from 0.
        required: false
        schema:
          type: integer
          format: int32
          default: 0
        example: 0
      - name: size
        in: query
        description: Defines the number of items to be displayed on a page. If the number specified is more than allowed max page size, the API will automatically adjust the page size to the max page size.
        required: false
        schema:
          type: integer
          format: int32
          default: 100
        example: 10
      - name: keyValueFilter
        in: query
        description: 'Filters results based on key-value pairs. Format: ''key1|value1,key2|value2''. This will add a filter on normalizedFlow collection directly instead of running query on atlas.'
        required: false
        schema:
          type: string
          default: ''
        example: activityName|Queue,flowType|FLOW
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowSearchResponse'
        '400':
          description: Bad request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
        '500':
          description: Internal Server Error
          content: {}
  /{orgId}/project/{projectId}/flows/{flowId}:
    delete:
      tags:
      - Flows
      summary: Delete a Flow or Subflow
      description: 'Permanently deletes a flow or subflow. Flows deleted via this API are removed permanently and cannot be recovered.


        Scope: `cjp:config_write`. Roles: [`Organizational Full Admin`, `Contact Center Service Admin`]'
      operationId: deleteFlowUsingDELETE
      parameters:
      - name: orgId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
        example: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
      - name: projectId
        in: path
        description: 'Project ID. System generated value which is the same across orgs and environments. Always use: 5e5c9ad6d61f870d6d778c1b.'
        required: true
        schema:
          type: string
        example: 5e5c9ad6d61f870d6d778c1b
      - name: flowId
        in: path
        description: ID of the flow/subflow to delete.
        required: true
        schema:
          type: string
        example: 661c7bc712eaf357de7e4aeb
      - name: force
        in: query
        description: If 'yes', the flow is deleted even if it is still referenced by other entities. Defaults to 'no'.
        required: false
        schema:
          type: string
          default: 'no'
        example: 'no'
      - name: skipRsEPCheck
        in: query
        description: If true, skips the check for routing strategy and entry point associations before deleting the flow.
        required: false
        schema:
          type: boolean
          default: true
        example: true
      - name: flowType
        in: query
        description: Either of 'FLOW' or 'SUBFLOW'.
        required: false
        schema:
          type: string
          default: FLOW
        example: FLOW
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
                example: OK
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
        '500':
          description: Internal Server Error
          content: {}
  /{orgId}/project/{projectId}/flows/{flowId}:publish:
    post:
      tags:
      - Flows
      summary: Publish a Flow or Subflow
      description: 'Returns the published flow in response.


        The Publish API validates the basic structure of the flows. We recommend manually verifying the published flows before proceeding with live traffic.


        Scope: `cjp:config_write`. Roles: [`Organizational Full Admin`, `Supervisor`, `Contact Center Service Admin`, `User Admin`]'
      operationId: publishFlowVersionUsingPOST
      parameters:
      - name: flowId
        in: path
        description: ID of the flow/subflow to publish.
        required: true
        schema:
          type: string
        example: 661c7bc712eaf357de7e4aeb
      - name: orgId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
        example: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
      - name: projectId
        in: path
        description: 'Project ID. System generated value which is the same across orgs and environments. Always use: 5e5c9ad6d61f870d6d778c1b.'
        required: true
        schema:
          type: string
        example: 5e5c9ad6d61f870d6d778c1b
      - name: TrackingId
        in: header
        description: ID for tracking.
        schema:
          type: string
        example: 491fed1e-de7f-11ef-9cd2-0242ac120002
      - name: skipValidation
        in: query
        description: If true, the flow's pre-publish validation is skipped. Use with care.
        required: false
        schema:
          type: boolean
          default: false
        example: false
      - name: flowType
        in: query
        description: Either of 'FLOW' or 'SUBFLOW'.
        required: false
        schema:
          type: string
          default: FLOW
        example: FLOW
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishParameters'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowRes'
        '201':
          description: Created
          content: {}
        '400':
          description: Bad request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      x-codegen-request-body-name: PublishParameters
  /{orgId}/project/{projectId}/flows/{flowId}:lock:
    post:
      tags:
      - Flows
      summary: Lock a Flow or Subflow
      description: 'Lock a flow to prevent concurrent edits by other users. Locks expire after 15 minutes of inactivity.


        Scope: `cjp:config_write`. Roles: [`Organizational Full Admin`, `Contact Center Service Admin`]'
      operationId: lockFlowUsingPOST
      parameters:
      - name: flowId
        in: path
        description: Flow ID.
        required: true
        schema:
          type: string
        example: 661c7bc712eaf357de7e4aeb
      - name: orgId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
        example: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
      - name: projectId
        in: path
        description: 'Project ID. System generated value which is the same across orgs and environments. Always use: 5e5c9ad6d61f870d6d778c1b.'
        required: true
        schema:
          type: string
        example: 5e5c9ad6d61f870d6d778c1b
      - name: flowType
        in: query
        description: Either of 'FLOW' or 'SUBFLOW'.
        required: false
        schema:
          type: string
          default: FLOW
        example: FLOW
      responses:
        '200':
          description: Lock confirmation with expiry information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowLockResponse'
        '401':
          description: Unauthorized.
          content: {}
        '403':
          description: Forbidden.
          content: {}
        '404':
          description: Not Found.
          content: {}
        '409':
          description: Conflict — the flow is already locked by another user.
          content: {}
        '429':
          description: Too Many Requests.
          content: {}
  /{orgId}/project/{projectId}/flows/{flowId}:unlock:
    post:
      tags:
      - Flows
      summary: Unlock a Flow or Subflow
      description: 'Release the lock on a flow to allow other users to edit it.


        Scope: `cjp:config_write`. Roles: [`Organizational Full Admin`, `Contact Center Service Admin`]'
      operationId: unlockFlowUsingPOST
      parameters:
      - name: flowId
        in: path
        description: Flow ID.
        required: true
        schema:
          type: string
        example: 661c7bc712eaf357de7e4aeb
      - name: orgId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
        example: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
      - name: projectId
        in: path
        description: 'Project ID. System generated value which is the same across orgs and environments. Always use: 5e5c9ad6d61f870d6d778c1b.'
        required: true
        schema:
          type: string
        example: 5e5c9ad6d61f870d6d778c1b
      - name: flowType
        in: query
        description: Either of 'FLOW' or 'SUBFLOW'.
        required: false
        schema:
          type: string
          default: FLOW
        example: FLOW
      responses:
        '200':
          description: Unlock confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowLockResponse'
        '401':
          description: Unauthorized.
          content: {}
        '403':
          description: Forbidden.
          content: {}
        '404':
          description: Not Found.
          content: {}
        '429':
          description: Too Many Requests.
          content: {}
  /{orgId}/project/{projectId}/v2/flows:validate:
    post:
      tags:
      - Flows
      summary: Validate a Flow
      description: 'Dry-run validate a flow definition without persisting it. Use this to check correctness before importing.


        Note: validation is more lenient than import. A flow that passes `:validate` can still be rejected by `:import` (for example, a missing start activity), so a successful validation does not guarantee a successful import.


        Scope: `cjp:config_write`'
      operationId: validateFlowV2
      parameters:
      - name: orgId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
        example: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
      - name: projectId
        in: path
        description: 'Project ID. System generated value which is the same across orgs and environments. Always use: 5e5c9ad6d61f870d6d778c1b.'
        required: true
        schema:
          type: string
        example: 5e5c9ad6d61f870d6d778c1b
      requestBody:
        description: Flow JSON document to validate.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlowV2'
        required: true
      responses:
        '200':
          description: Validation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowV2ValidationResult'
        '400':
          description: Bad Request — Invalid flow schema or missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowV2ErrorResponse'
        '401':
          description: Unauthorized.
          content: {}
        '403':
          description: Forbidden.
          content: {}
        '404':
          description: Not Found.
          content: {}
        '429':
          description: Too Many Requests.
          content: {}
  /{orgId}/project/{projectId}/v2/flows:import:
    post:
      tags:
      - Flows
      summary: Import a Flow
      description: 'Import a new flow from a flow definition. Creates the flow in draft state and returns the assigned flow metadata, including `flowId`.


        Scope: `cjp:config_write`'
      operationId: importFlowV2
      parameters:
      - name: orgId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
        example: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
      - name: projectId
        in: path
        description: 'Project ID. System generated value which is the same across orgs and environments. Always use: 5e5c9ad6d61f870d6d778c1b.'
        required: true
        schema:
          type: string
        example: 5e5c9ad6d61f870d6d778c1b
      - name: overwrite
        in: query
        description: If true, replaces an existing flow with the same name. Defaults to false.
        required: false
        schema:
          type: boolean
          default: false
        example: false
      - name: flowType
        in: query
        description: Either of 'FLOW' or 'SUBFLOW'.
        required: false
        schema:
          type: string
          default: FLOW
        example: FLOW
      requestBody:
        description: Flow JSON document to import.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlowV2'
        required: true
      responses:
        '201':
          description: Created — flow metadata including the assigned `flowId`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowV2Metadata'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowV2ErrorResponse'
        '401':
          description: Unauthorized.
          content: {}
        '403':
          description: Forbidden.
          content: {}
        '404':
          description: Not Found.
          content: {}
        '409':
          description: Conflict — a flow with the same name already exists and `overwrite` is false.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowV2ErrorResponse'
        '422':
          description: Unprocessable Entity — flow document failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowV2ValidationResult'
        '429':
          description: Too Many Requests.
          content: {}
  /{orgId}/project/{projectId}/v2/flows/{flowId}:
    get:
      tags:
      - Flows
      summary: Get a Flow
      description: 'Retrieve the current draft of a flow as a flow document. To fetch a specific published version, use the `:export` endpoint.


        Scope: `cjp:config_read`'
      operationId: getFlowV2
      parameters:
      - name: orgId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
        example: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
      - name: projectId
        in: path
        description: 'Project ID. System generated value which is the same across orgs and environments. Always use: 5e5c9ad6d61f870d6d778c1b.'
        required: true
        schema:
          type: string
        example: 5e5c9ad6d61f870d6d778c1b
      - name: flowId
        in: path
        description: Flow ID.
        required: true
        schema:
          type: string
        example: 661c7bc712eaf357de7e4aeb
      - name: flowType
        in: query
        description: Either of 'FLOW' or 'SUBFLOW'.
        required: false
        schema:
          type: string
          default: FLOW
        example: FLOW
      responses:
        '200':
          description: Flow JSON document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowV2'
        '401':
          description: Unauthorized.
          content: {}
        '403':
          description: Forbidden.
          content: {}
        '404':
          description: Not Found.
          content: {}
        '429':
          description: Too Many Requests.
          content: {}
    post:
      tags:
      - Flows
      summary: Save a Flow Draft
      description: 'Save a complete flow document as the current draft, replacing the existing draft. Pass `expectedVersion` as a query parameter to enable optimistic locking; the request fails with `409 Conflict` if the server-side version does not match. Omit `expectedVersion` to skip the check.


        Scope: `cjp:config_write`'
      operationId: saveFlowV2Draft
      parameters:
      - name: orgId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
        example: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
      - name: projectId
        in: path
        description: 'Project ID. System generated value which is the same across orgs and environments. Always use: 5e5c9ad6d61f870d6d778c1b.'
        required: true
        schema:
          type: string
        example: 5e5c9ad6d61f870d6d778c1b
      - name: flowId
        in: path
        description: Flow ID.
        required: true
        schema:
          type: string
        example: 661c7bc712eaf357de7e4aeb
      - name: expectedVersion
        in: query
        description: Expected current draft version for optimistic locking. The request fails with 409 Conflict if the server-side version does not match. Omit to skip the check.
        required: false
        schema:
          type: integer
          format: int32
        example: 3
      - name: flowType
        in: query
        description: Either of 'FLOW' or 'SUBFLOW'.
        required: false
        schema:
          type: string
          default: FLOW
        example: FLOW
      requestBody:
        description: Complete Flow JSON document.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlowV2'
        required: true
      responses:
        '200':
          description: Updated flow metadata, including the new `version`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowV2Metadata'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowV2ErrorResponse'
        '401':
          description: Unauthorized.
          content: {}
        '403':
          description: Forbidden.
          content: {}
        '404':
          description: Not Found.
          content: {}
        '409':
          description: Conflict — `expectedVersion` does not match the current draft version.
          content: {}
        '422':
          description: Unprocessable Entity — flow document failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowV2ValidationResult'
        '429':
          description: Too Many Requests.
          content: {}
    patch:
      tags:
      - Flows
      summary: Patch a Flow Draft
      description: 'Apply partial updates to an existing flow draft without replacing the entire document. The patch body is a Patch Draft Contract — server-side merge, idempotent, and re-validated after the merge. The patch is rejected if the merged document fails validation, so the draft is never left in a broken state. The body may also include top-level overrides such as `name` and `description`.


        Pass `expectedVersion` as a query parameter to enable optimistic locking; the request fails with `409 Conflict` if the server-side version does not match. Omit `expectedVersion` to skip the check.


        Scope: `cjp:config_write`'
      operationId: patchFlowV2Draft
      parameters:
      - name: orgId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
        example: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
      - name: projectId
        in: path
        description: 'Project ID. System generated value which is the same across orgs and environments. Always use: 5e5c9ad6d61f870d6d778c1b.'
        required: true
        schema:
          type: string
        example: 5e5c9ad6d61f870d6d778c1b
      - name: flowId
        in: path
        description: Flow ID.
        required: true
        schema:
          type: string
        example: 661c7bc712eaf357de7e4aeb
      - name: expectedVersion
        in: query
        description: Expected current draft version for optimistic locking. The request fails with 409 Conflict if the server-side version does not match. Omit to skip the check.
        required: false
        schema:
          type: integer
          format: int32
        example: 3
      - name: flowType
        in: query
        description: Either of 'FLOW' or 'SUBFLOW'.
        required: false
        schema:
          type: string
          default: FLOW
        example: FLOW
      requestBody:
        description: Patch Draft Contract document.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchDraftContract'
        required: true
      responses:
        '200':
          description: Updated flow metadata, including the new `version`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowV2Metadata'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowV2ErrorResponse'
        '401':
          description: Unauthorized.
          content: {}
        '403':
          description: Forbidden.
          content: {}
        '404':
          description: Not Found.
          content: {}
        '409':
          description: Conflict — `expectedVersion` does not match the current draft version.
          content: {}
        '422':
          description: Unprocessable Entity — merged flow document failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowV2ValidationResult'
        '429':
          description: Too Many Requests.
          content: {}
  /{orgId}/project/{projectId}/v2/flows/{flowId}:validate:
    get:
      tags:
      - Flows
      summary: Validate an Existing Flow Draft
      description: 'Validate the current draft of an existing flow (read-only operation).


        Scope: `cjp:config_read`'
      operationId: validateExistingFlowV2
      parameters:
      - name: orgId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
        example: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
      - name: projectId
        in: path
        description: 'Project ID. System generated value which is the same across orgs and environments. Always use: 5e5c9ad6d61f870d6d778c1b.'
        required: true
        schema:
          type: string
        example: 5e5c9ad6d61f870d6d778c1b
      - name: flowId
        in: path
        description: Flow ID.
        required: true
        schema:
          type: string
        example: 661c7bc712eaf357de7e4aeb
      - name: versionId
        in: query
        description: Version to validate. Use 'draft' for the current draft, or a specific version ObjectId.
        required: false
        schema:
          type: string
          default: draft
        example: draft
      - name: flowType
        in: query
        description: Either of 'FLOW' or 'SUBFLOW'.
        required: false
        schema:
          type: string
          default: FLOW
        example: FLOW
      responses:
        '200':
          description: Validation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowV2DraftValidationResult'
        '401':
          description: Unauthorized.
          content: {}
        '403':
          description: Forbidden.
          content: {}
        '404':
          description: Not Found.
          content: {}
        '429':
          description: Too Many Requests.
          content: {}
  /{orgId}/project/{projectId}/v2/flows/{flowId}:export:
    get:
      tags:
      - Flows
      summary: Export a Flow
      description: 'Export a flow as a flow document for backup, migration, or version control.


        Scope: `cjp:config_read`'
      operationId: exportFlowV2
      parameters:
      - name: orgId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
        example: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
      - name: projectId
        in: path
        description: 'Project ID. System generated value which is the same across orgs and environments. Always use: 5e5c9ad6d61f870d6d778c1b.'
        required: true
        schema:
          type: string
        example: 5e5c9ad6d61f870d6d778c1b
      - name: flowId
        in: path
        description: Flow ID.
        required: true
        schema:
          type: string
        example: 661c7bc712eaf357de7e4aeb
      - name: version
        in: query
        description: Version to export. Use 'latest' for the most recent published version, 'draft' for the working copy, or a specific version ObjectId.
        required: false
        schema:
          type: string
          default: latest
        example: latest
      - name: flowType
        in: query
        description: Either of 'FLOW' or 'SUBFLOW'.
        required: false
        schema:
          type: string
          default: FLOW
        example: FLOW
      responses:
        '200':
          description: Flow JSON document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowV2'
        '401':
          description: Unauthorized.
          content: {}
        '403':
          description: Forbidden.
          content: {}
        '404':
          description: Not Found.
          content: {}
        '429':
          description: Too Many Requests.
          content: {}
components:
  schemas:
    ActivityRes:
      title: ActivityRes
      type: object
      properties:
        group:
          type: string
          description: Group of the activity. It is one of 'start', 'action', 'event', and 'end'.
          example: start
        id:
          type: string
          description: Activity ID
          example: 9813529a-b01a-4eee-a79c-5016f7b0c772
        name:
          type: string
          description: Activity label
          example: NewPhoneContact
        properties:
          type: object
          properties: {}
          description: Additional properties are stored here
          example:
            displayName: NewPhoneContact
    FlowSearchResponse:
      title: FlowSearchResponse
      type: object
      description: Paginated list of flows matching the search criteria.
      example:
        pageInfo:
          currentPage: 0
          totalRecords: 8
          pageSize: 3
          totalPages: 3
        data:
        - orgId: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
          id: 6501eae8d7974a1c1d4c25d3
          name: Test_Flow
          flowType: FLOW
          lastModifiedDate: '2026-02-10T01:59:02.213Z'
      properties:
        pageInfo:
          $ref: '#/components/schemas/FlowSearchPageInfo'
        data:
          type: array
          description: Flows matching the search criteria for the current page.
          items:
            $ref: '#/components/schemas/FlowSearchResult'
    FlowVersionRes:
      title: FlowVersionRes
      type: object
      description: Represents a specific version of a flow or subflow, including diagram, process, variables, and validation details.
      example:
        id: 65c28d9db2a2375974066579
        flowId: 661c7bc712eaf357de7e4aeb
        name: TestFlow
        flowType: FLOW
        orgId: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
        version: 1
        validating: false
      properties:
        associatedChannels:
          type: array
          description: Channels associated with the flow version. Export and import payloads preserve this metadata so channel-specific activities, such as custom messaging activities, can be validated and resolved correctly.
          items:
            $ref: '#/components/schemas/AssociatedChannelRes'
          example:
          - channelType: customMessaging
            id: f47ac10b-58cc-4372-a567-0e02b2c3d479
            name: Task Queue 1
        comment:
          type: string
          description: Publish note
          example: This flow version has the Set-Variable activity
        createdBy:
          type: string
          description: Email of the account which created the flow version
          example: user@company.com
        createdDate:
          type: string
          description: Date of creation of the version object
          example: '2024-02-07T14:10:50.663Z'
          format: date-time
        description:
          type: string
          description: Description of the Flow Version
          example: This flow version has the 'Live' tag
        diagram:
          $ref: '#/components/schemas/DiagramRes'
        eventFlows:
          $ref: '#/components/schemas/EventDiagramRes'
        flowId:
          type: string
          description: Flow/Subflow ID to which the version belongs
          example: 661c7bc712eaf357de7e4aeb
        flowType:
          type: string
          description: Flow Type (FLOW/SUBFLOW). Default value is FLOW
          example: FLOW
        id:
          type: string
          description: Version object ID
          example: 65c28d9db2a2375974066579
        lastModifiedBy:
          type: string
          description: Email of the account which modified the flow version last
          example: user@company.com
        lastModifiedDate:
          type: string
          description: Date the version object is last modified
          example: '2024-02-07T14:10:50.663Z'
          format: date-time
        name:
          type: string
          description: Name of the Flow Version
          example: TestFlow
        orgId:
          type: string
          description: Organization ID
          example: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
        persist:
          type: boolean
          description: Determines whether the version object needs to be persisted in the DB
          example: true
        process:
          $ref: '#/components/schemas/ProcRes'
        runtimeVariables:
          type: array
          description: Output variables of the activities configured in the flow
          example:
          - name: NewPhoneContact.ANI
            type: string
            path: ''
            source: Event
            activityName: ANI
            displayName: ''
            uiVisible: true
            description: ''
          items:
            $ref: '#/components/schemas/UiRuntimeVariableRes'
        settings:
          type: array
          description: Settings for the flow version
          example:
          - name: showActivityWait
            value: 'true'
          - '`type`': BOOLEAN
            group: activityWait
          - name: delayTime
            value: '2000'
          - '`type`': INTEGER
            group: activityWait
          items:
            $ref: '#/components/schemas/FlowVersionSettingRes'
        validating:
          type: boolean
          description: Determines whether the version object needs to be validated
          example: false
        validationResults:
          type: array
          description: Validation errors are stored here
          items:
            $ref: '#/components/schemas/ValidationResultRes'
        variableOrders:
          type: object
          description: Determines the order in which variables appear in the Agent's desktop
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/VariableOrderRes'
          example:
            pop-over:
            - name: ani
              variableSeq: '0'
        variables:
          type: array
          description: Variables in the version object
          items:
            $ref: '#/components/schemas/FlowVariablesRes'
        version:
          type: integer
          description: Version Number
          format: int32
          example: 1
    FlowV2ValidationResult:
      title: FlowV2ValidationResult
      type: object
      description: Result of validating a flow document.
      example:
        valid: false
        errors:
        - activityName: start
          condition: onTimeoutBOGUS
          from: NewContact
          suggestion: 'Use one of: out'
          message: Condition 'onTimeoutBOGUS' is not valid for activity 'start'.
          severity: ERROR
          edge: NewContact->WelcomeMessage(onTimeoutBOGUS)
        warnings:
        - severity: RECOMMENDATION
          code: FC1007
          message: Add descriptions for activities
        summary: 1 error(s), 1 warning(s).
      properties:
        valid:
          type: boolean
          description: True if the document passed validation.
        errors:
          type: array
          description: Blocking errors. Empty when `valid` is true.
          items:
            $ref: '#/components/schemas/FlowV2ValidationError'
        warnings:
          type: array
          description: Non-blocking warnings and recommendations.
          items:
            $ref: '#/components/schemas/FlowV2ValidationWarning'
        summary:
          type: string
          description: Human-readable summary of the validation outcome.
          example: FlowV2 looks valid for import/save.
    DiagramRes:
      title: DiagramRes
      type: object
      description: Represents the visual graph metadata for a flow, including widgets and additional diagram properties.
      example:
        properties:
          activityId: http-request-v2
        widgets:
          493751c9-7b87-4e93-9999-084f89f9e17b:
            id: 6a59e2f5-3d3d-475a-91f7-d24ac25a614b
            type: start
            widgetType: activity
            label: New Activity Widget in Diagram
      properties:
        properties:
          type: object
          description: Additional properties are listed here
          properties: {}
          example:
            activityId: http-request-v2
        widgets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Widget'
          description: Holds the activities and links
          example:
            493751c9-7b87-4e93-9999-084f89f9e17b:
              id: 6a59e2f5-3d3d-475a-91f7-d24ac25a614b
              type: start
              widgetType: activity
              label: New Activity Widget in Diagram
    FlowV2EventFlow:
      title: FlowV2EventFlow
      type: object
      description: An event-handler subflow bound to a specific event. The subflow runs when its bound event fires.
      additionalProperties: true
      properties:
        event:
          type: string
          description: Name of the event this subflow handles. Must reference an event from `listEventSpecifications`.
          example: AgentDisconnected
        nodes:
          type: array
          description: Activity nodes in the event-handler process.
          items:
            $ref: '#/components/schemas/FlowV2Node'
        edges:
          type: array
          description: Edges in the event-handler process.
          items:
            $ref: '#/components/schemas/FlowV2Edge'
    FlowV2Summary:
      title: FlowV2Summary
      type: object
      description: Server-side metadata for a persisted flow document.
      additionalProperties: true
      properties:
        id:
          type: string
          description: Server-assigned flow ID.
          example: 661c7bc712eaf357de7e4aeb
        orgId:
          type: string
          description: Organization ID that owns the flow.
          example: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
        version:
          type: integer
          format: int64
          description: Current version number of the flow document.
          example: 0
        flowType:
          type: string
          description: Flow type. One of `FLOW` or `SUBFLOW`.
          enum:
          - FLOW
          - SUBFLOW
          example: FLOW
        name:
          type: string
          description: Flow name.
          example: SamplePlayMessageFlow
        description:
          type: string
          description: Human-readable description of the flow.
          example: 'Minimal sample flow: greet the caller, then disconnect'
        status:
          type: string
          description: Lifecycle state. One of `Draft` or `Published`.
          enum:
          - Draft
          - Published
          example: Draft
        createdBy:
          type: string
          description: User ID that created the flow.
          example: user@example.com
        createdDate:
          type: string
          format: date-time
          description: Timestamp the flow was first created.
          example: '2026-01-15T09:12:00.000Z'
        lastModifiedBy:
          type: string
          description: User ID that last modified the flow.
          example: user@example.com
        lastModifiedDate:
          type: string
          format: date-time
          description: Timestamp the flow was last modified.
          example: '2026-05-20T14:30:00.000Z'
      example:
        id: 661c7bc712eaf357de7e4aeb
        orgId: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
        version: 0
        flowType: FLOW
        name: SamplePlayMessageFlow
        description: 'Minimal sample flow: greet the caller, then disconnect'
        status: Draft
        createdBy: user@example.com
        createdDate: '2026-01-15T09:12:00.000Z'
        lastModifiedBy: user@example.com
        lastModifiedDate: '2026-05-20T14:30:00.000Z'
    EventDiagramRes:
      title: EventDiagramRes
      type: object
      description: Represents event-specific flow diagrams and global event mappings for a flow version.
      example:
        eventsMap:
          GLOBAL_EVENTS:
            id: GLOBAL_EVENTS
            name: name
            description: description
        properties:
          offsetX: '0'
      properties:
        eventsMap:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/EventFlowRes'
          description: Holds global events
          example:
            GLOBAL_EVENTS:
              id: GLOBAL_EVENTS
              name: name
              description: description
              process:
                activities:
                  13ae6d9e-e607-4e43-aab7-a1af579953a7:
                    id: 13ae6d9e-e607-4e43-aab7-a1af579953a7
                    name: GlobalErrorHandling
                    group: event
                    properties:
                      displayName: OnGlobalError
                      name: GlobalErrorHandling
                      event: OnGlobalError
                links:
                - id: db8170a0-ab4f-4415-8a3b-4561807a5287
                  sourceActivityId: 493751c9-7b87-4e93-9999-084f89f9e17b
                  targetActivityId: e1e7266d-699b-4420-8ba1-109d5d97f144
                  conditionExpr: out
                  properties:
                    value: out
              onEvents:
                GlobalErrorHandling: 13ae6d9e-e607-4e43-aab7-a1af579953a7
              diagram:
                widgets:
                  13ae6d9e-e607-4e43-aab7-a1af579953a7:
                    id: 14fd05ea-62f8-4003-8ad4-9599b8434dd7
                    type: event
                    widgetType: activity
                    label: New Activity Widget in Diagram
        properties:
          type: object
          properties: {}
          description: Holds information on additional properties
          example:
            offsetX: '0'
    FlowRes:
      title: FlowRes
      type: object
      example:
        id: 65c28d9db2a2375974066579
        projectId: 5e5c9ad6d61f870d6d778c1b
        orgId: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
        flowType: FLOW
        status: Draft
        version: 1
      properties:
        associatedChannels:
          type: array
          description: Channels associated with the flow.
          items:
            $ref: '#/components/schemas/AssociatedChannelRes'
          example:
          - channelType: customMessaging
            id: f47ac10b-58cc-4372-a567-0e02b2c3d479
            name: Task Queue 1
        assignedRS:
          uniqueItems: true
          type: array
          description: Assigned Routing Strategy.
          example:
          - RS1
          - RS2
          items:
            type: string
        createdBy:
          type: string
          description: Email of the account which created the flow.
          example: user@company.com
        createdDate:
          type: string
          description: Date of creation of the flow.
          format: date-time
          example: '2024-02-07T14:10:50.663Z'
        draftVersion:
          $ref: '#/components/schemas/FlowVersionRes'
        flowType:
          type: string
          description: Either of 'FLOW' or 'SUBFLOW.
          example: FLOW
        flowVersions:
          type: array
          description: Published FlowVersions for this flow.
          example:
          - 65c28d9db2a2375974066579
          - 75974065c28d9db3665792a2
          items:
            type: string
            description: Flow Version object ID to with which the tag is currently associated.
            example: 65c28d9db2a2375974066579
        id:
          type: string
          description: Flow ID
          example: 65c28d9db2a2375974066579
        lastModifiedBy:
          type: string
          description: Email of the account which modified the flow last.
          example: user@company.com
        lastModifiedDate:
          type: string
          description: Date the flow object is last modified.
          example: '2024-02-07T14:10:50.663Z'
          format: date-time
        latestVersion:
          $ref: '#/components/schemas/FlowVersionRes'
        lockedAt:
          type: string
          description: Moment at which a user began editing the flow and locked the flow for everyone else.
          format: date-time
          example: '2024-02-07T14:10:50.663Z'
        lockedBy:
          type: string
          description: Email of the account which is currently editing the flow.
          example: user@company.com
        orgId:
          type: string
          description: Organization ID.
          example: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
        preferences:
          type: array
          description: Flow preferences
          items:
            $ref: '#/components/schemas/FlowPreferenceRes'
        projectId:
          type: string
          description: 'Project ID. System generated value which is the same across orgs and environments. Always use: 5e5c9ad6d61f870d6d778c1b'
          example: 5e5c9ad6d61f870d6d778c1b
        status:
          type: string
          description: Indicates if this flow has ever been published - is one of 'Draft' or 'Published'.
          example: Draft
        tagHistories:
          type: object
          description: Histories of the tags. Tracks how the tags have been assigned to versions chronologically
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/FlowProgressionRes'
          example:
            Latest:
            - fvId: 63e3fcb0b57f601a2ad62db4
              fvName: HttpTraceTest
              forkFrom: 63e3fcb0b57f601a2ad62db4
        tags:
          type: array
          description: Flow tags
          items:
            $ref: '#/components/schemas/FlowTagRes'
        validating:
          type: boolean
          description: Determines whether the version object needs to be validated.
          example: false
        version:
          type: integer
          description: Version Number.
          format: int32
          example: 1
    LinkRes:
      title: LinkRes
      type: object
      properties:
        conditionExpr:
          type: string
          description: Condition expression. It is one of 'out', and 'default'
          example: out
        id:
          type: string
          description: Link ID
          example: dea7d650-9734-4fa3-bfc9-2c669415c9e3
        properties:
          type: object
          properties: {}
          description: Additional properties are stored here
          example:
            value: out
        sourceActivityId:
          type: string
          description: Activity from which the link originates
          example: 1330315f-7012-479a-8126-c767258004e6
        targetActivityId:
          type: string
          description: Activity to which the link connects
          example: 22a8930c-0770-4ab9-8e29-3a5ff1000e81
    AssociatedChannelRes:
      title: AssociatedChannelRes
      type: object
      description: Represents a channel associated with a flow version.
      properties:
        channelType:
          type: string
          description: Channel type associated with the flow version.
          example: customMessaging
        id:
          type: string
          description: Identifier of the associated channel.
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
        name:
          type: string
          description: Display name of the associated channel.
          example: Task Queue 1
    FlowV2Metadata:
      title: FlowV2Metadata
      type: object
      description: Result envelope returned for a flow on import, save draft, and patch draft. The persisted flow document is returned under `flow` (the server-assigned flow ID is `flow.id`), alongside any preflight warnings raised during the operation.
      additionalProperties: true
      properties:
        flow:
          description: The persisted flow document, including the server-assigned `id`.
          allOf:
          - $ref: '#/components/schemas/FlowV2Summary'
        preflightWarnings:
          type: array
          description: Non-blocking warnings raised while persisting the flow (for example, references that resolve but are flagged for review). Empty when there are none.
          items:
            type: object
            additionalProperties: true
          example: []
        preflightWarningsCount:
          type: integer
          format: int32
          description: Number of entries in `preflightWarnings`.
          example: 0
      example:
        flow:
          id: 661c7bc712eaf357de7e4aeb
          orgId: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
          version: 0
          flowType: FLOW
          name: SamplePlayMessageFlow
          description: 'Minimal sample flow: greet the caller, then disconnect'
          status: Draft
          createdBy: user@example.com
          createdDate: '2026-01-15T09:12:00.000Z'
          lastModifiedBy: user@example.com
          lastModifiedDate: '2026-05-20T14:30:00.000Z'
        preflightWarnings: []
        preflightWarningsCount: 0
    FlowSearchPageInfo:
      title: FlowSearchPageInfo
      type: object
      description: Pagination metadata for a flow search response.
      properties:
        currentPage:
          type: integer
          description: Zero-based index of the current page.
          format: int32
          example: 0
        totalRecords:
          type: integer
          description: Total number of flows matching the search criteria across all pages.
          format: int32
          example: 8
        pageSize:
          type: integer
          description: Number of items on the current page.
          format: int32
          example: 3
        totalPages:
          type: integer
          description: Total number of pages available for the search criteria.
          format: int32
          example: 3
    EventFlowRes:
      title: EventFlowRes
      type: object
      properties:
        description:
          type: string
          description: Description of the event pane
          example: description
        diagram:
          $ref: '#/components/schemas/DiagramRes'
        id:
          type: string
          description: Identifier of the event pane
          example: GLOBAL_EVENTS
        name:
          type: string
          description: Name of the event pane
          example: name
        onEvents:
          type: object
          additionalProperties:
            type: string
            description: Holds event IDs
            example: 13ae6d9e-e607-4e43-aab7-a1af579953a7
          description: List of events to which the flow version subscribes
          example:
            GlobalErrorHandling: 13ae6d9e-e607-4e43-aab7-a1af579953a7
        process:
          $ref: '#/components/schemas/ProcRes'
    ProcRes:
      title: ProcRes
      type: object
      description: Represents the executable process graph for a flow version, including activities and links.
      example:
        activities:
          493751c9-7b87-4e93-9999-084f89f9e17b:
            id: 493751c9-7b87-4e93-9999-084f89f9e17b
            name: NewPhoneContact
            group: start
        links:
        - id: dea7d650-9734-4fa3-bfc9-2c669415c9e3
          sourceActivityId: 1330315f-7012-479a-8126-c767258004e6
          targetActivityId: 22a8930c-0770-4ab9-8e29-3a5ff1000e81
          conditionExpr: out
      properties:
        activities:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ActivityRes'
          description: Stores list of activities/events
          example:
            493751c9-7b87-4e93-9999-084f89f9e17b:
              id: 493751c9-7b87-4e93-9999-084f89f9e17b
              name: NewPhoneContact
              group: start
              properties:
                name: NewPhoneContact
                event: NewPhoneContact
                activityId: start
        links:
          type: array
          description: Stores list of links
          items:
            $ref: '#/components/schemas/LinkRes'
    UiRuntimeVariableRes:
      title: UiRuntimeVariableRes
      type: object
      properties:
        activityName:
          type: string
          description: Name of the activity
          example: http-request-v2
        description:
          type: string
          description: Determines whether the variable needs to be visible on the UI
          example: HTTPRequest_7sz
        displayName:
          type: string
          description: Display name of the activity
          example: HTTPRequest_7sz
        isSecure:
          type: boolean
          description: Determines whether a variable is marked sensitive
          example: false
        name:
          type: string
          description: Name of the runtime variable
          example: NewPhoneContact.ANI
        path:
          type: string
          description: Path of the runtime variable
          example: HTTPRequest_7sz.httpResponseBody
        source:
          type: string
          description: Source of the runtime variable. Either 'Event' or 'Activity'
          example: Activity
        type:
          type: string
          description: Data type of the runtime variable
          example: string
        uiVisible:
          type: boolean
          description: Determines whether the variable needs to be visible on the UI
          example: false
    FlowLockResponse:
      title: FlowLockResponse
      type: string
      description: Lock/unlock acknowledgement. Returns the literal JSON string "OK" on success. Locks auto-expire after 15 minutes of inactivity.
      example: OK
    Widget:
      title: Widget
      type: object
      properties:
        id:
          type: string
          description: Widget ID of the entity
          example: 6a59e2f5-3d3d-475a-91f7-d24ac25a614b
        type:
          type: string
          description: Type of the widget. One of 'start', 'action', and 'end'
          example: start
        label:
          type: string
          description: Label of the widget
          example: New Activity Widget in Diagram
        widgetType:
          type: string
          description: Either 'activity' or 'link'
          example: activity
    BasicFlow:
      title: BasicFlow
      type: object
      example:
        id: 65c28d9db2a2375974066579
        name: TestFlow
        flowType: FLOW
        status: Draft
        orgId: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
        version: 1
      properties:
        associatedChannels:
          type: array
          description: Channels associated with the flow.
          items:
            $ref: '#/components/schemas/AssociatedChannelRes'
          example:
          - channelType: customMessaging
            id: f47ac10b-58cc-4372-a567-0e02b2c3d479
            name: Task Queue 1
        assignedRS:
          uniqueItems: true
          type: array
          description: Assigned Routing Strategy
          example:
          - rs-id1
          items:
            type: string
        createdBy:
          type: string
          description: Email of the account which created the flow
          example: user@company.com
        createdDate:
          type: string
          description: Date of creation of the flow
          example: '2024-02-07T14:10:50.663Z'
          format: date-time
        description:
          type: string
          description: Description of the flow
          example: This flow is updated with the 'Live' tag
        flowType:
          type: string
          description: Flow Type (FLOW/SUBFLOW). Default value is FLOW
          example: FLOW
        id:
          type: string
          description: Flow/Subflow ID
          example: 65c28d9db2a2375974066579
        lastModifiedBy:
          type: string
          description: Email of the account which modified the flow last
          example: user@company.com
        lastModifiedDate:
          type: string
          description: Date the flow object is last modified
          example: '2024-02-07T14:10:50.663Z'
          format: date-time
        lockedAt:
          type: string
          description: Moment at which a user began editing the flow and locked the flow for everyone else
          example: '2024-02-07T14:10:50.663Z'
          format: date-time
        lockedBy:
          type: string
          description: Email of the account which is currently editing the flow
          example: user@company.com
        name:
          type: string
          description: Name of the Flow
          example: TestFlow
        orgId:
          type: string
          description: Organization ID
          example: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
        status:
          type: string
          description: Indicates if this flow has ever been published - is one of 'Draft' or 'Published'
          example: Draft
        tagHistories:
          type: object
          description: Histories of the tags. Tracks how the tags have been assigned to versions chronologically
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/FlowProgressionRes'
          example:
            Latest:
            - fvId: 63e3fcb0b57f601a2ad62db4
              fvName: HttpTraceTest
              forkFrom: 63e3fcb0b57f601a2ad62db4
        tags:
          type: array
          description: Tags used by the flow
          items:
            $ref: '#/components/schemas/FlowTagRes'
        version:
          type: integer
          description: Version Number
          format: int32
          example: 1
    VariableOrderRes:
      title: VariableOrderRes
      type: object
      properties:
        name:
          type: string
          description: Name of the variable in the flow version object
          example: var1
        variableSeq:
          type: string
          description: Sequence number of the variable
          example: '1'
    FlowV2Variable:
      title: FlowV2Variable
      type: object
      description: A flow variable.
      additionalProperties: true
      properties:
        name:
          type: string
          description: Variable name.
          example: FlowVar1
        type:
          type: string
          description: Variable data type (for example, `STRING`, `INTEGER`, `BOOLEAN`).
          example: STRING
        value:
          type: string
          description: Default value as a string.
          example: var1
        description:
          type: string
          description: Human-readable description of the variable.
          example: ''
        isCAD:
          type: boolean
          description: True if this variable is exposed as Call-Associated Data.
          example: true
        isAgentEditable:
          type: boolean
          description: True if agents can edit the variable value at runtime.
          example: true
        isReportable:
          type: boolean
          description: True if the variable is included in reporting.
          example: false
        isSecure:
          type: boolean
          description: True if the variable holds sensitive data and must be masked in logs and reports.
          example: false
    FlowPreferenceRes:
      title: FlowPreferenceRes
      type: object
      properties:
        name:
          type: string
          description: The flow preference name.
          example: hideSecureCADWarning
        type:
          type: string
          description: The preference type.
          example: Boolean
        value:
          type: string
          description: The preference value.
          example: 'true'
    FlowV2Edge:
      title: FlowV2Edge
      type: object
      description: 'An edge connecting two flow nodes. Edge `condition` aliases are normalized server-side: `done` is rewritten to `out`, `NewPhoneContact` is rewritten to `out`, and `defaultBranch` is rewritten to `default`.'
      additionalProperties: true
      properties:
        key:
          type: string
          description: Stable, unique edge key within the flow. Used as the patch-merge key for `upsert_edges` and `remove_edge_keys`.
          example: edge-1
        from_node:
          type: string
          description: Name of the source node. Must reference a node in the same process.
          example: NewPhoneContact
        from_port:
          type: string
          description: Output port name on the source node. Must match an `outputPorts[].name` exposed by the source activity definition.
          example: out
        to_node:
          type: string
          description: Name of the target node. Must reference a node in the same process.
          example: PlayMessage_1
        condition:
          type: string
          description: 'Branch condition this edge fires on. Aliases: `done` -> `out`, `NewPhoneContact` -> `out`, `defaultBranch` -> `default`.'
          example: out
    FlowV2:
      title: FlowV2
      type: object
      description: Flow JSON document (formerly Flow IR / FDL 2.0). Describes a flow as top-level metadata plus arrays of nodes, edges, variables, event flows, and preferences.
      additionalProperties: true
      properties:
        flowName:
          type: string
          description: Name of the flow.
          example: Customer_Support_Main
        flowType:
          type: string
          description: Flow type. One of `FLOW` or `SUBFLOW`.
          enum:
          - FLOW
          - SUBFLOW
          example: FLOW
        contactType:
          type: string
          description: Channel type the flow is intended for (for example, `telephony`, `customMessaging`, `workItem`, `genericAction`).
          example: telephony
        description:
          type: string
          description: Human-readable description of the flow.
          example: Routes inbound support calls to the main support queue.
        version:
          type: integer
          format: int64
          description: Monotonically increasing version number of the document.
          example: 3
        status:
          type: string
          description: Lifecycle state of the document. One of `Draft` or `Published`.
          enum:
          - Draft
          - Published
          example: Draft
        nodes:
          type: array
          description: Activity nodes in the main flow process.
          items:
            $ref: '#/components/schemas/FlowV2Node'
        edges:
          type: array
          description: Edges connecting nodes in the main flow process.
          items:
            $ref: '#/components/schemas/FlowV2Edge'
        variables:
          type: array
          description: Flow variables.
          items:
            $ref: '#/components/schemas/FlowV2Variable'
        eventFlows:
          type: array
          description: Event-handler subflows bound to specific events.
          items:
            $ref: '#/components/schemas/FlowV2EventFlow'
        preferences:
          type: array
          description: Flow-level preferences.
          items:
            $ref: '#/components/schemas/FlowV2Preference'
      example:
        flowName: Customer_Support_Main
        flowType: FLOW
        contactType: telephony
        description: Routes inbound support calls to the main support queue.
        version: 3
        status: Draft
        nodes:
        - name: NewPhoneContact
          activityName: NewPhoneContact
          inputs: {}
          outputs: {}
          position:
            x: 100
            y: 200
        - name: PlayMessage_1
          activityName: PlayMessage
          inputs:
            audioFile: welcome.wav
          outputs: {}
          position:
            x: 300
            y: 200
        edges:
        - key: edge-1
          from_node: NewPhoneContact
          from_port: out
          to_node: PlayMessage_1
          condition: out
        variables:
        - name: FlowVar1
          type: STRING
          value: var1
          description: ''
          isCAD: true
          isAgentEditable: true
          isReportable: false
          isSecure: false
        eventFlows: []
        preferences:
        - name: hideSecureCADWarning
          type: Boolean
          value: 'true'
    FlowProgressionRes:
      title: FlowProgressionRes
      type: object
      properties:
        forkFrom:
          type: string
          description: Previous Flow Version holding the tag
          example: 65c28d9db2a2375974066579
        fvId:
          type: string
          description: Flow Version object ID
          example: 65c28d9db2a2375974066579
        fvName:
          type: string
          description: Name of the Flow Version object
          example: TestFlow
    FlowV2Preference:
      title: FlowV2Preference
      type: object
      description: A flow-level preference.
      additionalProperties: true
      properties:
        name:
          type: string
          description: Preference name.
          example: hideSecureCADWarning
        type:
          type: string
          description: Preference value type.
          example: Boolean
        value:
          type: string
          description: Preference value, encoded as a string.
          example: 'true'
    FlowV2ErrorResponse:
      title: FlowV2ErrorResponse
      type: object
      description: Standard error envelope returned by flow endpoints. For 400 (bad request) and 422 (validation failure), `details[]` carries field-level error information.
      additionalProperties: true
      example:
        code: INVALID_FLOW
        message: Flow document failed validation.
        details:
        - path: /nodes/2/inputs/queue
          code: UNKNOWN_QUEUE
          message: Queue 'Main_Support_Quueue' was not found in the project.
      properties:
        code:
          type: string
          description: Stable, machine-readable error code.
          example: INVALID_FLOW
        message:
          type: string
          description: Human-readable error message.
          example: Flow document failed validation.
        details:
          type: array
          description: Per-issue error details. Populated for 400 and 422 responses.
          items:
            $ref: '#/components/schemas/FlowV2ValidationError'
    FlowVariablesRes:
      title: FlowVariablesRes
      type: object
      properties:
        description:
          type: string
          description: Description for the variable
          example: var1 is meant for loop counter
        desktopLabel:
          type: string
          description: Variable name shown on Agent Desktop
          example: var1
        id:
          type: string
          description: Identifier for the variable
          example: 04b302a9-6d92-4365-8902-9b04bc3bf5f9
        isAgentEditable:
          type: boolean
          description: Determines whether is eligible for desktop agent to edit
          example: false
        isCAD:
          type: boolean
          description: Determines whether variable is agent viewable
          example: false
        isReportable:
          type: boolean
          description: Determines whether a variable is reportable
          example: false
        isSecure:
          type: boolean
          description: Determines whether a variable is marked sensitive
          example: false
        name:
          type: string
          description: Name of the variable
          example: var1
        overwrite:
          type: boolean
          description: Determines whether a global variable has been overwritten
          example: false
        source:
          type: string
          description: Source of the variable (GLOBAL, SUBFLOW_INPUT, SUBFLOW_OUTPUT, an empty string ). It's left empty for subflow local or flow variables
          example: GLOBAL
        type:
          type: string
          description: Data type of the variable (STRING, INTEGER, DATETIME, DECIMAL, JSON, BOOLEAN)
          example: STRING
        value:
          type: string
          description: Value of the variable
          example: hello world!
    FlowSearchResult:
      title: FlowSearchResult
      type: object
      description: Summary information for a flow returned by the search API.
      properties:
        orgId:
          type: string
          description: Organization ID.
          example: 8eb7da9a-c81c-4d13-b08b-38fdeb7330d8
        id:
          type: string
          description: Flow ID.
          example: 6501eae8d7974a1c1d4c25d3
        name:
          type: string
          description: Name of the flow.
          example: Test_Flow
        flowType:
          type: string
          description: Either of 'FLOW' or 'SUBFLOW'.
          example: FLOW
        lastModifiedDate:
          type: string
          description: Date the flow was last modified.
          format: date-time
          example: '2026-02-10T01:59:02.213Z'
    FlowTagRes:
      title: FlowTagRes
      type: object
      description: Represents a tag
      properties:
        default:
          type: boolean
          description: Determines whether the tag is a default tag
          example: false
        displayName:
          type: string
          description: Display name of the tag. It is one of 'Live', 'Test', 'Dev', 'Latest'
          example: Live
        flowVersionId:
          type: string
          description: Flow Version object ID to with which the tag is currently associated.
          example: 65c28d9db2a2375974066579
        id:
          type: string
          description: Identifier of the tag. It is one of 'Live', 'Test', 'Dev', 'Latest
          example: Live
        versionNumber:
          type: integer
          description: Associated Flow Version object's version number
          format: int32
          example: 1
    FlowV2ValidationError:
      title: FlowV2ValidationError
      type: object
      description: A single validation error against a flow document.
      properties:
        activityName:
          type: string
          description: Name of the activity the error relates to.
          example: play-message
        condition:
          type: string
          description: Edge condition the error relates to, when applicable.
          example: onTimeout
        from:
          type: string
          description: Source node label of the offending edge, when applicable.
          example: WelcomeMessage
        edge:
          type: string
          description: Human-readable description of the offending edge, when applicable.
          example: WelcomeMessage->DisconnectContact(onTimeout)
        suggestion:
          type: string
          description: Suggested fix.
          example: 'Use one of: default, error'
        message:
          type: string
          description: Human-readable explanation of the error.
          example: Condition 'onTimeout' is not valid for activity 'play-message'.
        severity:
          type: string
          description: Severity of the issue.
          enum:
          - ERROR
          example: ERROR
    FlowV2DraftValidationEntry:
      title: FlowV2DraftValidationEntry
      type: object
      description: A single result entry returned when validating a stored flow draft.
      properties:
        code:
          type: string
          description: Stable result code.
          example: FC1007
        docLink:
          type: string
          description: Link to documentation about this result. May be empty.
          example: ''
        hint:
          type: string
          description: Additional hint about the result, when available.
          example: Flow has isolated activities. Ensure all nodes are reachable from the start node.
        message:
          type: string
          description: Human-readable explanation of the result.
          example: Add descriptions for activities
        severity:
          type: string
          description: Severity of the result.
          enum:
          - ERROR
          - WARNING
          - RECOMMENDATION
          example: RECOMMENDATION
        activityLabel:
          type: string
          description: Label of the activity the result relates to. May be empty.
          example: ''
    ValidationResultRes:
      title: ValidationResultRes
      type: object
      properties:
        activityId:
          type: string
          description: Activity identifier
          example: e0d7128e-0f80-46c8-9554-9a9ae4dd9e7b
        activityLabel:
          type: string
          description: Activity label
          example: PlayMessage_ysg
        code:
          type: string
          description: Error code
          example: FC1015
        docLink:
          type: string
          description: Document link
          example: https://help.webex.com/en-us/article/n5595zd/Webex-Contact-Center-Setup-and-Administration-Guide
        message:
          type: string
          description: Error message to be displayed on the UI
          example: Add descriptions for activities
        severity:
          type: string
          description: Severity of the error. Either ERROR or RECOMMENDATION
          example: ERROR
    FlowV2ValidationWarning:
      title: FlowV2ValidationWarning
      type: object
      description: A single non-blocking validation warning or recommendation against a flow document.
      properties:
        severity:
          type: string
          description: Severity of the issue.
          enum:
          - WARNING
          - RECOMMENDATION
          example: RECOMMENDATION
        code:
          type: string
          description: Stable warning code.
          example: FC1007
        message:
          type: string
          description: Human-readable explanation of the warning.
          example: Add descriptions for activities
    FlowV2Node:
      title: FlowV2Node
      type: object
      description: A node in a flow process graph. Each node represents one activity instance.
      additionalProperties: true
      properties:
        name:
          type: string
          description: Stable, unique node name within the flow. Used as the patch-merge key for `upsert_nodes` and `remove_node_names`.
          example: PlayMessage_1
        activityName:
          type: string
          description: Activity type this node instantiates. Must match an `activityName` returned by `listActivityDefinitions`.
          example: PlayMessage
        inputs:
          type: object
          description: Input values for the activity, keyed by input name. Shape depends on the activity definition.
          additionalProperties: true
          example:
            audioFile: welcome.wav
        outputs:
          type: object
          description: Declared output bindings for the activity, keyed by output name. Used to map activity outputs to flow variables.
          additionalProperties: true
          example: {}
        position:
          type: object
          description: Node position on the flow canvas.
          properties:
            x:
              type: number
              description: Horizontal coordinate in pixels.
              example: 300
            y:
              type: number
              description: Vertical coordinate in pixels.
              example: 200
    PatchDraftContract:
      title: PatchDraftContract
      type: object
      description: Structured patch applied to a flow draft. Server-side merge, idempotent, and re-validated after the merge — the patch is rejected if the merged document fails validation.
      properties:
        upsert_nodes:
          type: array
          description: Nodes to insert or replace. Matched by `name`. If a node with the same name exists, it is fully replaced; otherwise a new node is created.
          items:
            type: object
            additionalProperties: true
        upsert_edges:
          type: array
          description: Edges to insert or replace, matched by `id`.
          items:
            type: object
            additionalProperties: true
        remove_node_names:
          type: array
          description: Names of nodes to remove. Edges referencing a removed node must also be removed in the same patch, or the merged document will fail validation.
          items:
            type: string
        remove_edge_keys:
          type: array
          description: Identifiers of edges to remove.
          items:
            type: string
      example:
        upsert_nodes:
        - id: node-welcome
          name: WelcomeMessage
          activityType: action
          properties:
            activityName: play-message
            prompt:
              promptType: text
              text: Thanks for calling. Please hold.
              textType: text
        upsert_edges:
        - id: edge-1
          from: NewContact
          to: WelcomeMessage
          condition: out
          properties: {}
        remove_node_names: []
        remove_edge_keys: []
    FlowV2DraftValidationResult:
      title: FlowV2DraftValidationResult
      type: object
      description: Result of validating a stored flow draft. Issues are returned under `results`.
      example:
        valid: true
        results:
        - code: FC1007
          docLink: ''
          message: Add descriptions for activities
          severity: RECOMMENDATION
          activityLabel: ''
      properties:
        valid:
          type: boolean
          description: True if the draft passed validation.
        results:
          type: array
          description: Per-issue results.
          items:
            $ref: '#/components/schemas/FlowV2DraftValidationEntry'
    PublishParameters:
      title: PublishParameters
      type: object
      description: Metadata for the published version.
      properties:
        comment:
          type: string
          description: A comment to provide context on publishing the flow.
          example: Publishing the latest version
        tagIds:
          type: array
          description: Tag IDs appropriate to this version. It must be one of 'Live', 'Test', 'Dev', 'Latest.
          example:
          - Live
          items:
            type: string
    FlowVersionSettingRes:
      title: FlowVersionSettingRes
      type: object
      properties:
        group:
          type: string
          description: The group the setting belongs to.
          example: activityWait
        name:
          type: string
          description: The name of the flow version setting
          example: delayTime
        type:
          type: string
          description: The setting type.
          example: INTEGER
        value:
          type: string
          description: The setting value.
          example: '2000'
  securitySchemes:
    oauth2:
      flows:
        authorizationCode:
          authorizationUrl: /
          scopes: {}
          tokenUrl: /
      type: oauth2
    bearer-key:
      type: http
      description: e.g. Bearer YOUR_AUTHORIZATION_TOKEN
      scheme: bearer
      bearerFormat: JWT
    BEARER_TOKEN_FROM_CI:
      type: http
      in: header
      scheme: bearer
    Bearer:
      type: http
      description: e.g. Bearer YOUR_AUTHORIZATION_TOKEN
      scheme: bearer
      bearerFormat: JWT
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT bearer token authentication. Obtain your token from the Webex Developer Portal.