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

# Invoke

> Run a workflow deployment with the public Fetch Hive API using a deployment name, variant, and start inputs

`POST /v1/workflow/invoke`

Run a workflow deployment from your own app or service.

## Authentication

Send your workspace API key in the `Authorization` header.

```bash theme={null}
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. |

`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:

```json theme={null}
{
  "metadata": {
    "customer_id": "cus_123",
    "plan": "enterprise",
    "trial": false,
    "invoice_count": 12,
    "region": null
  }
}
```

Invalid:

```json theme={null}
{
  "metadata": {
    "customer": {
      "id": "cus_123"
    },
    "tags": ["enterprise"]
  }
}
```

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.

{/* Add screenshot: Signing secret section in the workflow code snippet modal */}

## Response

When callback delivery is off, Fetch Hive waits for the workflow to finish and returns the output in one response.

```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."
}
```

`output` is shape-dependent by workflow result type. For image-generation final outputs, `output` is an object with `settings` and `assets`:

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

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

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "queued",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}
```

## Example

### Direct request

```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
```

### Callback delivery request

```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
```

## Related

* See [Authentication](./authentication) for API key setup
* See [Callback Delivery and Webhook Triggers](../workflows/async-and-webhooks) for callback delivery and signature verification
* See [Run with API](../workflows/run-with-api) for a workflow-focused guide