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

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

```json
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "completed",
  "output": {
    "settings": {
      "model": "grok-imagine-image-quality",
      "provider": "xai",
      "image_size": "1024x1024"
    },
    "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
{
  "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](/api-reference/authentication.md) 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](/workflows/async-and-webhooks.md) for webhook delivery and signature verification
* See [Run with API](/workflows/run-with-api.md) for a workflow-focused guide


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fetchhive.com/api-reference/invoke-workflow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.