# Invoke Prompt

`POST /v1/invoke`

Run a prompt 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 **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 |

## Response

If `streaming` is `true`, Fetch Hive returns a stream of events.

Example reasoning event:

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

Example response event:

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

Example final usage event:

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

If `streaming` is `false`, Fetch Hive returns one JSON response.

```json
{
  "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
curl 'https://api.fetchhive.com/v1/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."
    },
    "streaming": true
  }' \
  --compressed
```

## Related

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