Run with API

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:

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	Callback delivery settings. See Callback Delivery and Webhook Triggers
`metadata`	object	No	Flat 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:

Field	Type	Required	Description
`async.enabled`	boolean	Yes	Set to `true` to return immediately and deliver the result later by signed callback
`async.callback_url`	string	Yes when callback delivery is enabled	The 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.

Getting Started

Prompts

Workflows

Hive Agents

Agents

Knowledge Bases

Experiments

Your Workspace

Monitoring

User Tracking

Resources

Authentication

Endpoint

Request

Basic example

Callback delivery example

Response

Direct response

Callback delivery response

Errors

Next steps

​Authentication

​Endpoint

​Request

​Basic example

​Callback delivery example

​Response

​Direct response

​Callback delivery response

​Errors

​Next steps

Authentication

Endpoint

Request

Basic example

Callback delivery example

Response

Direct response

Callback delivery response

Errors

Next steps