Invoke

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	Callback delivery settings
`metadata`	object	No	Flat caller-defined metadata for audit and log filtering. This is not used as workflow input.
`tool_approval`	string	No	`policy` or `auto_approve`. Omit it, or send `policy`, to follow the deployment’s saved auto-approve switch. `auto_approve` applies to this call only when the API key is allowed to auto-approve actions.

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"]
  }
}

tool_approval does not change the deployment’s saved switch. Any other value returns 400 invalid_tool_approval. A key without the permission, a signed-in token, or a webhook that sends auto_approve returns 403 tool_approval_override_not_permitted and does not start a run. Destructive actions still ask. Deny rules still block the action. 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 callback delivery is enabled	The 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": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "file_url": "https://signed-download.example/...?X-Amz-Signature=...",
        "file_url_expires_at": "2026-08-11T12:00:00Z",
        "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

See Authentication for API key setup
See Callback Delivery and Webhook Triggers for callback delivery and signature verification
See Run with API for a workflow-focused guide

Fetch Hive API

REST API

Authentication

Request body

Response

Example

Direct request

Callback delivery request

​Authentication

​Request body

​Response

​Example

​Direct request

​Callback delivery request

​Related

Authentication

Request body

Response

Example

Direct request

Callback delivery request

Related