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

# Execute a workflow

> Run a published workflow. await=true returns results synchronously; await=false returns a tracking_id immediately. Resume a paused (input/human-in-the-loop) run by passing its run_id plus the human response as trigger.

Resuming a run that is not paused or errored answers 409; it does not start the flow again. The paused entry is claimed when the resume is accepted, so a second submit is refused. A call with `await: false` can now return an error, including start-up failures, and waits for the first stream write.



## OpenAPI

````yaml /api-reference/endpoint/hub-flows/openapi.json post /hub/workflows/run
openapi: 3.1.0
info:
  title: Flows API
  version: 1.2.0
  description: >-
    Flow collections, nodes and workflows in the QuivaWorks hub: create,
    publish, run, resume, monitor, and the integration OAuth connections flows
    use.
servers:
  - url: https://api.quiva.ai
    description: Production API server
security:
  - bearerAuth: []
  - apiKeyAuth: []
tags:
  - name: Collections
    description: Operations related to collections
  - name: Nodes
    description: Operations related to nodes
  - name: Workflows
    description: Operations related to workflows
  - name: Oauth
    description: Oauth configurations and connections
  - name: Schedules
  - name: Eval snippets
  - name: Marketplace
paths:
  /hub/workflows/run:
    post:
      summary: Execute a workflow
      description: >-
        Run a published workflow. await=true returns results synchronously;
        await=false returns a tracking_id immediately. Resume a paused
        (input/human-in-the-loop) run by passing its run_id plus the human
        response as trigger.


        Resuming a run that is not paused or errored answers 409; it does not
        start the flow again. The paused entry is claimed when the resume is
        accepted, so a second submit is refused. A call with `await: false` can
        now return an error, including start-up failures, and waits for the
        first stream write.
      operationId: runWorkflowBySubject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunWorkflowRequest'
            examples:
              sync:
                summary: Synchronous run
                value:
                  subject: ms.hub.config.workflow.4285896071.1009853675
                  trigger:
                    description: reverses a string
                  await: true
              resumePaused:
                summary: Resume a paused human-in-the-loop run
                value:
                  subject: ms.hub.config.workflow.4285896071.1009853675
                  run_id: >-
                    ms.hub.run.uuid123.ms.hub.config.workflow.4285896071.1009853675
                  trigger:
                    approved: true
                  await: true
      responses:
        '200':
          description: >-
            Run result. { tracking_id, result }. If config.result was set,
            result matches that JSONPath selection; otherwise result is the
            step-by-step log array where items with a 'paused': true flag
            indicate a human-in-the-loop pause (resume with run_id).
          content:
            application/json:
              example:
                tracking_id: ms.hub.run.abc123.ms.hub.config.workflow.4285896071.1009853675
                result: export function reverse(s){return [...s].reverse().join('')}
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          description: Workflow not found or not published
        '409':
          description: >-
            The run is not paused or errored, or there is no errors entry to
            retry. A second resume of the same pause is refused the same way.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    RunWorkflowRequest:
      type: object
      required:
        - subject
      properties:
        subject:
          type: string
          pattern: ^ms\.hub\.config\.workflow\.
          description: >-
            Workflow subject. Published:
            ms.hub.config.workflow.{collection}.{flow} (NO 'published' segment -
            get it from listWorkflows version=published). Draft:
            ms.hub.config.workflow.draft.{collection}.{flow}.
        trigger:
          type: object
          description: Run input, referenced in nodes via $.trigger
        triggers:
          type: array
          description: Batch execution (use either trigger or triggers)
          items:
            type: object
        await:
          type: boolean
          default: false
          description: >-
            true = wait for completion and return results; false = return
            tracking_id immediately
        enable_log:
          type: boolean
          default: true
          description: Store detailed run logs (searchable via searchRunLogs)
        knowledge:
          type: array
          description: 'Knowledge URIs for agents: kv://, obj://, str://, sid://, dta://'
          items:
            type: string
        session_id:
          type: string
          description: Agent conversation continuity; omit for new sessions
        run_id:
          type: string
          description: >-
            Full tracking id of a paused or errored run to resume
            (human-in-the-loop), in the form ms.hub.run.<uuid>.<flow subject>,
            as returned when the run started and by the paused-runs list. A bare
            uuid is rejected with 400 invalid run_id. Resuming a run that is not
            paused or errored returns 409.
        retry:
          type: boolean
          description: Retry a failed run
    Error:
      type: object
      properties:
        error:
          type: string
  responses:
    BadRequest:
      description: >-
        Invalid request or validation failure, e.g. { "error": "duplicate node
        id found: CODE_EXPERT" }
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

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