# 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](/api-reference/authentication.md) for API key setup
* See [Prompts](/prompts/prompts.md) for prompt editor and deployment context
* See [Run with API](/prompts/run-with-api.md) for a prompt-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-prompt.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.