Skip to main content
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. If an external product needs to start a workflow by sending a webhook directly to Fetch Hive, use the webhook trigger URL from the deployment helper instead. That flow uses X-Fetch-Hive-Webhook-Secret instead of a workspace API key. See Callback Delivery and Webhook Triggers.

​
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:
FieldTypeRequiredDescription
deploymentstringYesThe workflow deployment key
variantstringYesThe deployment variant you want to run
inputsobjectNoKey-value pairs for the variables defined on the workflow’s Start step
asyncobjectNoCallback delivery settings. See Callback Delivery and Webhook Triggers
metadataobjectNoFlat caller-defined metadata for audit and log filtering. This is not used as workflow input.
inputs values must match the workflow’s Start input types. Text inputs accept strings. Array inputs must be native JSON arrays, for example "companies": [{"name":"Fetch Hive"}]. Arrays are preserved as arrays in workflow variables and logs. metadata must be flat and scalar-only: strings, numbers, booleans, or null. Nested objects and arrays return a validation error before the run starts. If you include async, use these nested fields:
FieldTypeRequiredDescription
async.enabledbooleanYesSet to true to return immediately and deliver the result later by signed callback
async.callback_urlstringYes when callback delivery is enabledThe callback URL Fetch Hive should call when the run finishes
Workflows that contain a Human in the Loop step must use callback delivery. Set async.enabled to true and provide async.callback_url; synchronous invocation returns a validation error because the run pauses until the configured workspace member submits a choice.

​
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"
    },
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise"
    }
  }' \
  --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. Use metadata for audit fields you want to see or filter in logs, such as customer IDs, plan names, regions, or experiment names. Workflow start variables belong in inputs. See Invoke metadata for examples and log filtering details.

​
Callback delivery 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 Callback Delivery and Webhook Triggers for how immediate responses and signed callback delivery work.

​
Response

​
Direct response

When you do not enable callback delivery, 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."
}

​
Callback delivery 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 callback-delivery 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 Callback Delivery and Webhook Triggers for callback validation errors.

​
Next steps