Invoke Workflow

Run a workflow deployment with the public Fetch Hive API using a deployment name, variant, and start inputs

POST /v1/workflow/invoke

Run a workflow deployment from your own app or service.

Authentication

Send your workspace API key in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Request body

Open Workflows, then Deployments, open the deployment variant you want to run, and click Code Snippet to copy the current request shape from Fetch Hive.

Field	Type	Required	Description
deployment	string	Yes	The workflow deployment name
variant	string	Yes	The deployment variant name
inputs	object	No	Key-value pairs for the variables defined on the Start step
async	object	No	Async run settings

If you include async, use these nested fields:

Field	Type	Required	Description
async.enabled	boolean	Yes	Set to true to return immediately
async.callback_url	string	Yes when async is enabled	The webhook URL Fetch Hive should call when the run finishes

If you turn on Async in the code snippet dialog, Fetch Hive also shows a Signing secret for webhook verification.

Response

When async mode is off, Fetch Hive waits for the workflow to finish and returns the output in one response.

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "completed",
  "output": "State of enterprise AI in 2026: enterprises are moving from experimentation to operational systems with stricter evaluation, governance, and tooling requirements."
}

When async.enabled is true, Fetch Hive returns immediately.

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "running",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}

At high concurrency, Fetch Hive can also return a queued async state.

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "queued",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}

Example

Sync request

curl 'https://api.fetchhive.com/v1/workflow/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
    "deployment": "YOUR_DEPLOYMENT_NAME",
    "variant": "YOUR_VARIANT_NAME",
    "inputs": {
      "topic": "State of enterprise AI in 2026"
    }
  }' \
  --compressed

Async request

curl 'https://api.fetchhive.com/v1/workflow/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
    "deployment": "YOUR_DEPLOYMENT_NAME",
    "variant": "YOUR_VARIANT_NAME",
    "async": {
      "enabled": true,
      "callback_url": "https://example.com/callback"
    },
    "inputs": {
      "topic": "State of enterprise AI in 2026"
    }
  }' \
  --compressed

Related

• See Authentication for API key setup

• See Retrieve Run for workflow run lookup

• See Async and Webhooks for webhook delivery and signature verification

• See Run with API for a workflow-focused guide