Skip to main content
POST
/
api
/
v2
/
workflows
/
run
Run a workflow
curl --request POST \
  --url https://app.octavehq.com/api/v2/workflows/run \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "workflowOId": "caw_3rgkoHhR00cEdE9DjKeIK",
  "callbackUrl": "https://example.com/callback"
}
'
{
  "jobOId": "bsjob_3rgkoHhR00cEdE9DjKeIK",
  "status": "pending",
  "message": "Workflow execution started successfully"
}

​
How Workflow Input Works

Unlike the 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
  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: 
{
  "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: 
{
  "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:

Authorizations

​
api_key
string
header
required

Body

application/json
​
workflowOId
string
required

The OId of the workflow to run

Minimum string length: 1
Example:

"caw_3rgkoHhR00cEdE9DjKeIK"

​
callbackUrl
string<uri>

The URL to call back to when the workflow is complete

Example:

"https://example.com/callback"

​
{key}
unknown

Response

200 - application/json

Workflow execution started successfully

​
jobOId
string
required

The OId of the job that was created to run the workflow

Example:

"bsjob_3rgkoHhR00cEdE9DjKeIK"

​
status
enum<string>
required

The status of the job

Available options:
pending,
running
Example:

"pending"

​
message
string

The message from the job

Example:

"Workflow execution started successfully"