Skip to main content
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.
FieldTypeRequiredDescription
deploymentstringYesThe workflow deployment name
variantstringYesThe deployment variant name
inputsobjectNoKey-value pairs for the variables defined on the Start step
asyncobjectNoCallback delivery settings
metadataobjectNoFlat caller-defined metadata for audit and log filtering. This is not used as workflow input.
inputs values are validated against the workflow’s Start input definitions before the run starts. Array start inputs must be native JSON arrays, not JSON strings. metadata must be a flat object. Keys must be non-empty strings, and values must be strings, numbers, booleans, or null. Arrays and nested objects are rejected before the run starts. Valid: 
{
  "metadata": {
    "customer_id": "cus_123",
    "plan": "enterprise",
    "trial": false,
    "invoice_count": 12,
    "region": null
  }
}
Invalid: 
{
  "metadata": {
    "customer": {
      "id": "cus_123"
    },
    "tags": ["enterprise"]
  }
}
If you include async, use these nested fields:
FieldTypeRequiredDescription
async.enabledbooleanYesSet to true to return immediately
async.callback_urlstringYes when callback delivery is enabledThe callback URL Fetch Hive should call when the run finishes
If you turn on Callback delivery in the code snippet dialog, Fetch Hive also shows a Signing secret for callback verification.

​
Response

When callback delivery 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."
}
output is shape-dependent by workflow result type. For image-generation final outputs, output is an object with settings and assets: 
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "completed",
  "output": {
    "settings": {
      "model": "grok-imagine-image-quality",
      "provider": "xai",
      "image_count": 1
    },
    "assets": [
      {
        "id": "asset_1",
        "file_url": "https://uploads.fetchhive.com/...png",
        "file_name": "step_3_123456789_1.png",
        "file_size": 505042,
        "file_type": "image/png"
      }
    ]
  }
}
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 callback-delivery state. 
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "queued",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}

​
Example

​
Direct 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"
    },
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise"
    }
  }' \
  --compressed

​
Callback delivery 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