# Run with API

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.

## Authentication

```bash
Authorization: Bearer YOUR_API_KEY
```

See [API Keys](https://docs.fetchhive.com/your-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](https://docs.fetchhive.com/workflows/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       | Async run settings. See [Async and Webhooks](https://docs.fetchhive.com/workflows/async-and-webhooks) |

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

## Basic example

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

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

## Async example

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

See [Async and Webhooks](https://docs.fetchhive.com/workflows/async-and-webhooks) for how async responses and signed webhook delivery work.

## Response

### Sync response

When you do not enable async, the public route waits for the workflow to finish and returns the final output. For example:

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

### Async response

When `async.enabled` is `true`, the route returns immediately. For example:

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

At high concurrency, the route can also return a queued async state:

```json
{
  "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
{
  "error": "Missing required field: deployment or variant"
}
```

See [Error Handling](https://docs.fetchhive.com/workflows/error-handling) for workflow-specific failure cases and [Async and Webhooks](https://docs.fetchhive.com/workflows/async-and-webhooks) for async callback validation errors.

## Next steps

* [Async and Webhooks](https://docs.fetchhive.com/workflows/async-and-webhooks)
* [Error Handling](https://docs.fetchhive.com/workflows/error-handling)
* [Run with Python SDK](https://docs.fetchhive.com/workflows/run-with-python-sdk)
* [Run with Node.js SDK](https://docs.fetchhive.com/workflows/run-with-nodejs-sdk)