# 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](/your-workspace/api-keys.md) 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](/workflows/publishing-and-versioning.md) 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](/workflows/async-and-webhooks.md) |

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](/workflows/async-and-webhooks.md) 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](/workflows/error-handling.md) for workflow-specific failure cases and [Async and Webhooks](/workflows/async-and-webhooks.md) for async callback validation errors.

## Next steps

* [Async and Webhooks](/workflows/async-and-webhooks.md)
* [Error Handling](/workflows/error-handling.md)
* [Run with Python SDK](/workflows/run-with-python-sdk.md)
* [Run with Node.js SDK](/workflows/run-with-nodejs-sdk.md)
* [Run with Ruby SDK](/workflows/run-with-ruby-sdk.md)
* [Run with PHP SDK](/workflows/run-with-php-sdk.md)


---

# 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/workflows/run-with-api.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.