Run with API

Invoke a workflow deployment with the public API using your API key, deployment name, variant, and start inputs

Use the public workflow invoke endpoint when you want to run a workflow deployment from your own app or service. Create a workflow deployment in the dashboard, choose a variant, then use the deployment details in your request.

Authentication

Authorization: Bearer YOUR_API_KEY

See API Keys for how to create and manage keys.

Endpoint

POST https://api.fetchhive.com/v1/workflow/invoke

Before you call this endpoint, create a workflow deployment and variant from the workflow editor. See Publishing and Versioning for that UI flow.

Request

Use this request shape:

Field	Type	Required	Description
deployment	string	Yes	The workflow deployment key
variant	string	Yes	The deployment variant you want to run
inputs	object	No	Key-value pairs for the variables defined on the workflow's Start step
async	object	No	Async run settings. See Async and Webhooks

If you include async, use these nested fields:

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

Basic example

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

This matches the cURL snippet shown in the workflow deployment UI. The deployment UI currently shows a cURL example, and the Python and TypeScript tabs still show Coming Soon.

Async example

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

See Async and Webhooks for how async responses and signed webhook delivery work.

Response

Sync response

When you do not enable async, the public route waits for the workflow to finish and returns the final output. For example:

{
  "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."
}

Async response

When async.enabled is true, the route returns immediately. For example:

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

At high concurrency, the route can also return a queued async state:

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

Errors

The route returns an error object when the request is invalid or the run fails. For example:

{
  "error": "Missing required field: deployment or variant"
}

See Error Handling for workflow-specific failure cases and Async and Webhooks for async callback validation errors.

Next steps

• Async and Webhooks

• Error Handling

• Run with Python SDK

• Run with Node.js SDK