> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# [Beta] Invoke a workflow

> [Beta] Invoke a workflow — Run a workflow the same way the AI agent runs one during a conversation.



## OpenAPI

````yaml post /workflows/{workflow_id}/invoke
openapi: 3.1.0
info:
  title: OpenCX API
  description: >

    OpenCX is an AI-powered, all-in-one platform for customer support and
    outbound communications.


    Use this API to manage your OpenCX organization's AI agents, actions,
    conversations, contacts, and more.


    To get started, generate a new API key from the dashboard.


    ## Authentication

    All API endpoints require authentication using a Bearer token. You can
    generate an API key from your OpenCX dashboard.


    ## Rate Limiting

    API requests are rate limited to ensure fair usage. The current limits are:

    - 100 requests per minute for standard endpoints

    - 1000 requests per minute for streaming endpoints


    ## Error Handling

    The API uses standard HTTP status codes and returns detailed error messages
    in the response body.
  version: 1.0-beta
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: http://localhost:8080
    description: Development
  - url: https://api.open.cx
    description: Production
security:
  - bearerAuth: []
paths:
  /workflows/{workflow_id}/invoke:
    post:
      tags:
        - Workflows (Beta)
      summary: '[Beta] Invoke a workflow'
      description: >-
        Run a workflow the same way the AI agent runs one during a conversation.
        Handles the on-demand trigger types the agent can invoke — ai-trigger,
        manual-ticket-trigger, and manual-trigger — and rejects event-only
        workflows. `input` is the payload: the ai payload for ai-trigger, the
        form data for manual-ticket-trigger (manual-trigger takes none). With
        `context.sessionId`, the workflow runs with the same in-session ticket
        context the agent has (required for manual-ticket-trigger). This
        exposes, to a caller embedded in a conversation, the same workflows the
        agent can trigger in that session. Returns the run id, plus the terminal
        output when the workflow runs synchronously. An ai-trigger workflow
        limited to some channels (`sessionChannels` in its trigger
        configuration) answers 400 unless `context.sessionId` is a session on
        one of those channels. Answers 429 `feature_limit_reached` while a
        monthly billing usage limit covering the workflow is reached.
      operationId: invokeWorkflow
      parameters:
        - schema:
            type: string
          in: path
          name: workflow_id
          required: true
          description: The workflow UUID to invoke
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvokeWorkflowDto'
      responses:
        '201':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvokeWorkflowResponseDto'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
components:
  schemas:
    InvokeWorkflowDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/InvokeWorkflowDtoInput'
      type: object
      properties:
        input:
          default: {}
          description: Inputs for the workflow (ai payload / form data)
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
        context:
          type: object
          properties:
            sessionId:
              description: Conversation session for ticket context
              type: string
    InvokeWorkflowResponseDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/InvokeWorkflowResponseDto'
      type: object
      properties:
        run_id:
          type: string
          description: The id of the workflow run
        status:
          type: string
          enum:
            - completed
            - queued
          description: completed = ran synchronously; queued = running in the background
        output:
          description: Terminal output, present when the workflow ran synchronously
      required:
        - run_id
        - status
      additionalProperties: false
    ErrorDto:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.