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

# Run a workflow

> Runs a workflow asynchronously and returns a job OId to track execution.

The workflow's starting node (the node with no incoming edges) determines which agent runs first. Any additional fields in the request body beyond `workflowOId` and `callbackUrl` are forwarded as input to that starting node's agent.

The required input fields depend on the agent type configured on the workflow's starting node. Refer to the **Run Agent** (`/async/agent/run`) endpoint documentation for the input schema of each agent type.

## How Workflow Input Works

Unlike the [Run Agent](/v2-api-reference/async/run-agent) endpoint where you explicitly choose which agent type to run, a workflow's agent type is determined by its graph definition. The **entry node** of the workflow dictates what input fields are expected.

Any fields you include in the request body beyond `workflowOId` and `callbackUrl` are forwarded as `agentInputData` to the workflow's starting agent node.

### Determining Required Fields

1. Open your workflow in the [Octave dashboard](https://app.octavehq.com)
2. Identify the **entry node** and its agent type
3. Refer to the corresponding agent documentation for the expected input fields

### Example: Workflow Starting with Enrich Person

If your workflow's entry node is an **Enrich Person** agent, include person identification fields:

```json theme={null}
{
  "workflowOId": "caw_3rgkoHhR00cEdE9DjKeIK",
  "callbackUrl": "https://example.com/callback",
  "email": "john.doe@example.com",
  "firstName": "John",
  "companyDomain": "example.com",
  "companyName": "Example",
  "linkedInProfile": "https://www.linkedin.com/in/john-doe/"
}
```

### Example: Workflow Starting with Content Agent

If your workflow's entry node is a **Content** agent, include person/company context and optional output configuration:

```json theme={null}
{
  "workflowOId": "caw_3rgkoHhR00cEdE9DjKeIK",
  "callbackUrl": "https://example.com/callback",
  "email": "john.doe@example.com",
  "companyDomain": "example.com",
  "outputFormat": "MARKDOWN",
  "customContext": {
    "playbook": { "oId": "playbook_123" },
    "product": { "oId": "product_456" }
  }
}
```

### Agent Input Reference

See the individual agent endpoints for the full list of fields each agent type accepts:

* [Enrich Person Agent](/v2-api-reference/agents/enrich-person-agent)
* [Enrich Company Agent](/v2-api-reference/agents/enrich-company-agent)
* [Content Agent](/v2-api-reference/agents/content-agent)
* [Sequence Agent](/v2-api-reference/agents/sequence-agent)
* [Prospector Agent](/v2-api-reference/agents/prospector-agent)
* [Qualify Person Agent](/v2-api-reference/agents/qualify-person-agent)
* [Qualify Company Agent](/v2-api-reference/agents/qualify-company-agent)
* [Call Prep Agent](/v2-api-reference/agents/call-prep-agent)


## OpenAPI

````yaml post /api/v2/workflows/run
openapi: 3.0.0
info:
  version: 1.0.0
  title: Octave API
  description: API for Octave workspace management and AI-powered content generation
servers:
  - url: https://app.octavehq.com
security:
  - ApiKeyAuth: []
paths:
  /api/v2/workflows/run:
    post:
      tags:
        - Workflow
      summary: Run a workflow
      description: >-
        Runs a workflow asynchronously and returns a job OId to track execution.


        The workflow's starting node (the node with no incoming edges)
        determines which agent runs first. Any additional fields in the request
        body beyond `workflowOId` and `callbackUrl` are forwarded as input to
        that starting node's agent.


        The required input fields depend on the agent type configured on the
        workflow's starting node. Refer to the **Run Agent**
        (`/async/agent/run`) endpoint documentation for the input schema of each
        agent type.
      operationId: runWorkflow
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                workflowOId:
                  type: string
                  minLength: 1
                  description: The OId of the workflow to run
                  example: caw_3rgkoHhR00cEdE9DjKeIK
                callbackUrl:
                  type: string
                  format: uri
                  description: >-
                    Optional callback URL. If provided, results are POSTed to
                    this URL on completion. If omitted, poll GET
                    /workflows/run/status with the returned jobOId instead.
                  example: https://example.com/callback
              required:
                - workflowOId
              additionalProperties:
                nullable: true
              description: >-
                Workflow execution input. Additional properties beyond
                workflowOId and callbackUrl are passed as input to the starting
                node's agent. See /async/agent/run for agent-specific input
                schemas.
      responses:
        '200':
          description: Workflow execution started successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobOId:
                    type: string
                    description: The OId of the job that was created to run the workflow
                    example: bsjob_3rgkoHhR00cEdE9DjKeIK
                  message:
                    type: string
                    description: The message from the job
                    example: Workflow execution started successfully
                required:
                  - jobOId
      deprecated: false
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api_key

````