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"
}
'
import requests

url = "https://app.octavehq.com/api/v2/workflows/run"

payload = {
    "workflowOId": "caw_3rgkoHhR00cEdE9DjKeIK",
    "callbackUrl": "https://example.com/callback"
}
headers = {
    "api_key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {api_key: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    workflowOId: 'caw_3rgkoHhR00cEdE9DjKeIK',
    callbackUrl: 'https://example.com/callback'
  })
};

fetch('https://app.octavehq.com/api/v2/workflows/run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.octavehq.com/api/v2/workflows/run",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'workflowOId' => 'caw_3rgkoHhR00cEdE9DjKeIK',
    'callbackUrl' => 'https://example.com/callback'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "api_key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.octavehq.com/api/v2/workflows/run"

	payload := strings.NewReader("{\n  \"workflowOId\": \"caw_3rgkoHhR00cEdE9DjKeIK\",\n  \"callbackUrl\": \"https://example.com/callback\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api_key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://app.octavehq.com/api/v2/workflows/run")
  .header("api_key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"workflowOId\": \"caw_3rgkoHhR00cEdE9DjKeIK\",\n  \"callbackUrl\": \"https://example.com/callback\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://app.octavehq.com/api/v2/workflows/run")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api_key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"workflowOId\": \"caw_3rgkoHhR00cEdE9DjKeIK\",\n  \"callbackUrl\": \"https://example.com/callback\"\n}"

response = http.request(request)
puts response.read_body
{
  "jobOId": "bsjob_3rgkoHhR00cEdE9DjKeIK",
  "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

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.

​
workflowOId
string
required

The OId of the workflow to run

Minimum string length: 1
Example:

"caw_3rgkoHhR00cEdE9DjKeIK"

​
callbackUrl
string<uri>

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"

​
{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"

​
message
string

The message from the job

Example:

"Workflow execution started successfully"