> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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](./async-and-webhooks).

## Authentication

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

See [API Keys](../workspace/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](./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](./async-and-webhooks) |
| `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

```bash theme={null}
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](../user-tracking/invoke-metadata) for examples and log filtering details.

## Callback delivery example

```bash theme={null}
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](./async-and-webhooks) 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "error": "Missing required field: deployment or variant"
}
```

See [Error Handling](./error-handling) for workflow-specific failure cases and [Callback Delivery and Webhook Triggers](./async-and-webhooks) for callback validation errors.

## Next steps

* [Callback Delivery and Webhook Triggers](./async-and-webhooks)
* [Error Handling](./error-handling)
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Run with PHP SDK](./run-with-php-sdk)