> ## 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 prompt deployment with the public Fetch Hive API using a deployment name and variant

`POST /v1/prompt/invoke`

Run a prompt 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 **Prompts**, then **Deployments**, open the deployment variant you want to run, and click **Code Snippet** to see this request shape in Fetch Hive.

| Field        | Type    | Required | Description                                                                                 |
| ------------ | ------- | -------- | ------------------------------------------------------------------------------------------- |
| `deployment` | string  | Yes      | The prompt deployment name                                                                  |
| `variant`    | string  | Yes      | The deployment variant name                                                                 |
| `inputs`     | object  | No       | Key-value pairs for the prompt variables                                                    |
| `streaming`  | boolean | No       | Stream response events instead of waiting for one final JSON response                       |
| `metadata`   | object  | No       | Flat caller-defined metadata for audit and log filtering. This is not used as prompt input. |

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

`POST /v1/prompt/invoke` does not accept top-level `image_urls` or document
`attachments`. If a deployed prompt uses an image URL message part, configure
that image URL in the prompt editor or bind it through an `inputs` variable in
the prompt content. For runtime image/document attachments, use
[`POST /v1/agent/invoke`](../agents/invoke).

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

## Response

If `streaming` is `true`, Fetch Hive returns a stream of events. If the provider fails after the stream has opened, Fetch Hive sends a final `error` event before closing the stream.

Example reasoning event:

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "reasoning",
  "model": "gpt-5-nano",
  "response": " seems"
}
```

Example response event:

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "response",
  "model": "gpt-5-nano",
  "response": " too"
}
```

Example final usage event:

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "usage",
  "usage": {
    "duration": 4.79230260848999,
    "prompt_tokens": {
      "total_tokens": 24,
      "cached_tokens": 0
    },
    "completion_tokens": {
      "total_tokens": 170,
      "reasoning_tokens": 64
    },
    "total_tokens": 194
  },
  "stop_reason": "completed"
}
```

Example error event:

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "error",
  "error": "cohere provider stream error: HTTP 400: invalid request",
  "message": "cohere provider stream error: HTTP 400: invalid request",
  "provider": "cohere",
  "error_type": "provider_stream_error",
  "status_code": 502
}
```

If `streaming` is `false`, Fetch Hive returns one JSON response. Provider execution failures return `502 Bad Gateway` with an `error` message.

```json theme={null}
{
  "request_id": "req_019d528660dd7e22b15e5b13a1931c50",
  "model": "gpt-5-nano-2025-08-07",
  "duration": 4.641960144042969,
  "reasoning": "The request asks for a short summary.",
  "response": "Fetch Hive helps teams ship AI products faster.",
  "usage": {
    "prompt_tokens": {
      "total_tokens": 24,
      "cached_tokens": 0
    },
    "completion_tokens": {
      "total_tokens": 187,
      "reasoning_tokens": 64
    },
    "total_tokens": 211
  },
  "stop_reason": "completed"
}
```

## Example

```bash theme={null}
curl 'https://api.fetchhive.com/v1/prompt/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": {
      "text": "Fetch Hive helps teams ship AI products faster."
    },
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise"
    },
    "streaming": true
  }' \
  --compressed
```

## Webhook trigger

`POST /v1/prompt/webhooks/{prompt_endpoint_id}/variants/{variant_id}`

Use a prompt webhook trigger when an external service should start a deployed prompt variant without a workspace API key. The request must include the prompt endpoint webhook secret in `X-Fetch-Hive-Webhook-Secret`. If a third-party tool cannot set custom headers, use `?secret=YOUR_WEBHOOK_SECRET` as a fallback.

Webhook prompt triggers always use callback delivery. Include `async.callback_url`; Fetch Hive returns `202` with `request_id` and `run_status: "running"`, then delivers either `prompt.completed` or `prompt.failed` to the callback URL.

```bash theme={null}
curl 'https://api.fetchhive.com/v1/prompt/webhooks/YOUR_PROMPT_ENDPOINT_ID/variants/YOUR_VARIANT_ID' \
  -H 'X-Fetch-Hive-Webhook-Secret: YOUR_WEBHOOK_SECRET' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "inputs": {
      "text": "Fetch Hive helps teams ship AI products faster."
    },
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise"
    },
    "user": "external-user-1",
    "async": {
      "callback_url": "https://example.com/callback"
    }
  }'
```

`inputs` must be an object. Every variable declared on the selected deployed prompt version must be present, but values may be empty strings or `null` when you intentionally want a blank render. Extra input keys are allowed. `metadata` follows the same flat scalar-only rule as normal prompt invokes and appears in log filtering.

Fetch Hive signs the outbound callback with the same webhook secret used for inbound trigger authentication.
Callback `data` contains `response` on `prompt.completed` and `error` on `prompt.failed`; use the top-level `event_type` and `request_id` for terminal state and correlation.

## Related

* See [Authentication](./authentication) for API key setup
* See [Prompts](../prompts/overview) for prompt editor and deployment context
* See [Run with API](../prompts/run-with-api) for a prompt-focused guide