# Invoke Workflow

`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
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       | Async run settings                                              |

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 async is enabled | The webhook URL Fetch Hive should call when the run finishes |

If you turn on **Async** in the code snippet dialog, Fetch Hive also shows a **Signing secret** for webhook verification.

## Response

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

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

When `async.enabled` is `true`, Fetch Hive returns immediately.

```json
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "running",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}
```

At high concurrency, Fetch Hive can also return a queued async state.

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

## Example

### Sync request

```bash
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"
    }
  }' \
  --compressed
```

### Async request

```bash
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](https://docs.fetchhive.com/api-reference/authentication) for API key setup
* See [Retrieve Run](https://github.com/Jellyfishboy/fetchhive-api/blob/app-v3/LIVE_DOCS/api-reference/retrieve-run.md) for workflow run lookup
* See [Async and Webhooks](https://docs.fetchhive.com/workflows/async-and-webhooks) for webhook delivery and signature verification
* See [Run with API](https://docs.fetchhive.com/workflows/run-with-api) for a workflow-focused guide