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

# Start a workflow execution

> Start executing a workflow by its reference ID. Returns immediately with a run ID; execution proceeds in the background.
LLM credentials are resolved from each worker agent's configured LLM through the LLM Gateway.



## OpenAPI

````yaml https://api-trial.cognigy.ai/swagger/openapi.json post /executeworkflow
openapi: 3.0.3
info:
  contact:
    email: support@example.com
    name: API Support
  description: API for managing agents and related resources
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: http://swagger.io/terms/
  title: Agents API
  version: '1.0'
servers:
  - url: https://api-trial.cognigy.ai/v1
security:
  - ApiKey: []
tags:
  - name: Agents
  - name: Brand personas
  - name: Tools
  - name: Built-in tools
  - name: Skills
  - name: Built-in skills
  - name: MCP servers
  - name: Tool references
paths:
  /executeworkflow:
    post:
      tags:
        - workflows
      summary: Start a workflow execution
      description: >-
        Start executing a workflow by its reference ID. Returns immediately with
        a run ID; execution proceeds in the background.

        LLM credentials are resolved from each worker agent's configured LLM
        through the LLM Gateway.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_workflows.ExecuteWorkflowRequest'
        description: Workflow execution parameters
        required: true
        x-originalParamName: request
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_workflows.WorkflowRunResponse'
          description: Accepted
        '400':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailBadRequest
          description: Invalid request body or validation error
        '404':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailNotFound
          description: Workflow not found
        '500':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailInternalError
          description: Internal server error
components:
  schemas:
    internal_workflows.ExecuteWorkflowRequest:
      properties:
        projectId:
          example: 507f1f77bcf86cd799439011
          type: string
        userInput:
          example: >-
            Create a weather lookup tool that fetches current weather for a
            given city
          type: string
        workflowReferenceId:
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          type: string
      required:
        - projectId
        - userInput
        - workflowReferenceId
      type: object
    internal_workflows.WorkflowRunResponse:
      properties:
        completedAt:
          example: 1711929610
          type: integer
        createdAt:
          example: 1711929600
          type: integer
        currentStepId:
          example: extract-params
          type: string
        inputPrompt:
          example: Review and confirm the extracted parameters
          type: string
        runId:
          example: 507f1f77bcf86cd799439011
          type: string
        status:
          allOf:
            - $ref: '#/components/schemas/internal_workflows.RunStatus'
          example: running
        stepResults:
          items:
            $ref: '#/components/schemas/internal_workflows.StepResult'
          type: array
        userInput:
          example: Create a weather lookup tool
          type: string
        workflowReferenceId:
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          type: string
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailBadRequest:
      properties:
        detail:
          example: request body validation failed
          type: string
        errors:
          items:
            $ref: >-
              #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.FieldError
          type: array
        instance:
          example: /v1/{resource}
          type: string
        status:
          example: 400
          type: integer
        title:
          example: Bad Request
          type: string
        traceId:
          example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed
          type: string
        type:
          example: about:blank
          type: string
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailNotFound:
      properties:
        detail:
          example: the requested resource does not exist
          type: string
        instance:
          example: /v1/{resource}/{id}
          type: string
        status:
          example: 404
          type: integer
        title:
          example: Not Found
          type: string
        traceId:
          example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed
          type: string
        type:
          example: about:blank
          type: string
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailInternalError:
      properties:
        detail:
          example: internal server error
          type: string
        instance:
          example: /v1/{resource}
          type: string
        status:
          example: 500
          type: integer
        title:
          example: Internal Server Error
          type: string
        traceId:
          example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed
          type: string
        type:
          example: about:blank
          type: string
      type: object
    internal_workflows.RunStatus:
      enum:
        - pending
        - running
        - awaiting_input
        - completed
        - failed
        - cancelled
      type: string
      x-enum-varnames:
        - RunStatusPending
        - RunStatusRunning
        - RunStatusAwaitingInput
        - RunStatusCompleted
        - RunStatusFailed
        - RunStatusCancelled
    internal_workflows.StepResult:
      properties:
        endedAt:
          example: 1711929605
          type: integer
        error:
          type: string
        iteration:
          type: integer
        name:
          example: Extract Parameters
          type: string
        response:
          type: string
        sessionId:
          example: workflow-run-507f1f77bcf86cd799439011-step-extract-params
          type: string
        startedAt:
          example: 1711929601
          type: integer
        status:
          allOf:
            - $ref: '#/components/schemas/internal_workflows.RunStatus'
          example: completed
        stepId:
          example: extract-params
          type: string
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.FieldError:
      properties:
        field:
          type: string
        message:
          type: string
      type: object
  securitySchemes:
    ApiKey:
      description: '[Production] API key for production authentication'
      in: header
      name: X-API-Key
      type: apiKey

````