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

# Execute a workflow synchronously

> Executes a workflow and waits for it to complete before returning the result



## OpenAPI

````yaml /openapi.json post /workflow/run
openapi: 3.0.0
info:
  title: Output.ai API
  version: 1.0.0
  description: API for managing and executing Output.ai workflows
servers:
  - url: http://localhost:3001
    description: Development server
security: []
tags: []
paths:
  /workflow/run:
    post:
      summary: Execute a workflow synchronously
      description: >-
        Executes a workflow and waits for it to complete before returning the
        result
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - workflowName
                - input
              properties:
                workflowName:
                  type: string
                  description: The name of the workflow to execute
                input:
                  description: The payload to send to the workflow
                workflowId:
                  type: string
                  description: (Optional) The workflowId to use. Must be unique
                catalog:
                  type: string
                  description: >-
                    The catalog (Temporal task queue) to route the execution to.
                    Falls back to the default catalog.
                taskQueue:
                  type: string
                  deprecated: true
                  description: >-
                    Deprecated alias for `catalog`. If both are sent, `catalog`
                    wins.
                searchAttributes:
                  type: object
                  description: >-
                    (Optional) Temporal search attributes to set on the
                    execution. Each attribute must be registered on the
                    namespace. Values are scalars (string, number, boolean) or
                    string arrays (KeywordList). Unregistered names or values
                    that do not match the registered type are rejected with 400.
                  additionalProperties:
                    oneOf:
                      - type: string
                      - type: number
                      - type: boolean
                      - type: array
                        items:
                          type: string
                timeout:
                  type: number
                  description: >-
                    (Optional) The max time to wait for the execution, defaults
                    to 30s
      responses:
        '200':
          description: The workflow result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResultResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '408':
          $ref: '#/components/responses/RequestTimeout'
        '424':
          $ref: '#/components/responses/FailedDependency'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    WorkflowResultResponse:
      oneOf:
        - $ref: '#/components/schemas/WorkflowResultV2Response'
        - $ref: '#/components/schemas/WorkflowResultV1Response'
    WorkflowResultV2Response:
      type: object
      additionalProperties: false
      description: >-
        Current workflow result with direct output and memo-based trace
        information
      required:
        - v
        - workflowId
        - runId
        - status
        - input
        - output
        - trace
        - error
      properties:
        v:
          type: string
          enum:
            - '2'
          description: Workflow result response version
        workflowId:
          type: string
          description: The workflow execution id
        runId:
          type: string
          nullable: true
          description: The specific run id for this execution
        status:
          $ref: '#/components/schemas/WorkflowResultStatus'
        input:
          nullable: true
          description: The original input passed to the workflow, null if unavailable
        output:
          nullable: true
          description: Direct workflow output, null if no output is available
        trace:
          $ref: '#/components/schemas/TraceInfoV2'
        error:
          allOf:
            - $ref: '#/components/schemas/SerializedWorkflowError'
          nullable: true
    WorkflowResultV1Response:
      type: object
      deprecated: true
      additionalProperties: false
      description: Legacy wrapped workflow result
      required:
        - workflowId
        - runId
        - status
        - input
        - output
        - trace
        - error
        - errorDetails
      properties:
        workflowId:
          type: string
          description: The workflow execution id
        runId:
          type: string
          nullable: true
          description: The specific run id for this execution
        status:
          $ref: '#/components/schemas/WorkflowResultStatus'
        input:
          nullable: true
          description: The original input passed to the workflow, null if unavailable
        output:
          nullable: true
          description: The result of workflow, null if workflow failed
        trace:
          $ref: '#/components/schemas/TraceInfoV1'
        error:
          type: string
          nullable: true
          description: Error message if workflow failed, null otherwise
        errorDetails:
          type: object
          nullable: true
          description: Structured failure details if the workflow failed, null otherwise
          properties:
            message:
              type: string
              nullable: true
              description: Friendly failure message (from the underlying application error)
            name:
              type: string
              nullable: true
              description: Error name/type (the original error's class)
            retryable:
              type: boolean
              nullable: true
              description: Whether Temporal flagged the failure retryable; null if unknown
            activityId:
              type: string
              nullable: true
              description: >-
                Failing activity key ("workflow#step"); null if no activity
                failed
            cause:
              type: object
              nullable: true
              additionalProperties: true
              description: Sanitized error cause chain (name/message per level, no stack)
    ValidationErrorResponse:
      type: object
      description: Request body validation failure (Zod)
      properties:
        error:
          type: string
          enum:
            - ValidationError
        message:
          type: string
          example: Invalid Payload
        issues:
          type: array
          description: Zod validation issues
          items:
            type: object
    ErrorResponse:
      type: object
      description: >-
        API error body (WorkflowNotFoundError, UnsupportedWorkflowError,
        WorkflowExecutionTimedOutError, WorkflowNotCompletedError,
        CatalogNotAvailableError, or server error)
      properties:
        error:
          type: string
          description: >-
            Error type name (e.g. WorkflowNotFoundError,
            UnsupportedWorkflowError, CatalogNotAvailableError)
        message:
          type: string
          description: Human-readable error message
        workflowId:
          type: string
          description: >-
            Workflow ID when the error is tied to a specific execution (e.g.
            timeout)
          nullable: true
    WorkflowResultStatus:
      type: string
      enum:
        - completed
        - failed
        - cancelled
        - terminated
        - timed_out
        - continued_as_new
      description: The workflow execution status
    TraceInfoV2:
      type: object
      nullable: true
      description: Available destinations for trace data
      properties:
        local:
          type: string
          description: Absolute path to local trace file, omitted if not saved locally
        remote:
          type: string
          description: Remote trace location (e.g., S3 URI), omitted if not saved remotely
    SerializedWorkflowError:
      type: object
      nullable: true
      additionalProperties: true
      description: Structured error details captured from the workflow or activity failure
      properties:
        activityType:
          type: string
          description: >-
            Failing activity type, omitted when the failure did not originate in
            an activity
        name:
          type: string
          description: Original error class name
        message:
          type: string
          description: Original error message
    TraceInfoV1:
      type: object
      nullable: true
      description: Legacy trace information containing nested destinations
      properties:
        destinations:
          type: object
          description: Available destinations for trace data
          properties:
            local:
              type: string
              description: Absolute path to local trace file, omitted if not saved locally
            remote:
              type: string
              description: >-
                Remote trace location (e.g., S3 URI), omitted if not saved
                remotely
  responses:
    BadRequest:
      description: Invalid request body, query, or pagination token
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ValidationErrorResponse'
              - $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Workflow execution, workflow type, or catalog not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RequestTimeout:
      description: Synchronous execution timed out before workflow completed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    FailedDependency:
      description: >-
        Workflow dependency failed (e.g. workflow not in a terminal state, or
        workflow type is unsupported by the selected catalog)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error (e.g. Temporal connection failure)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: >-
        Catalog workflow unavailable (worker not running or still starting).
        Retry-After header may be set.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

````

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