# Run with API

Use the public invoke endpoint when you want to call a prompt from your own app or service. First create a prompt deployment and variant in the dashboard, then invoke the deployment with your workspace API key.

## 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/invoke`

Before you call this endpoint, create or update a prompt deployment from the prompt editor. See [Publishing and Versioning](https://docs.fetchhive.com/prompts/publishing-and-versioning) for the UI flow.

## Request

Use this request shape:

| Field        | Type    | Required | Description                                                 |
| ------------ | ------- | -------- | ----------------------------------------------------------- |
| `deployment` | string  | Yes      | The prompt deployment name you created for the prompt       |
| `variant`    | string  | Yes      | The prompt deployment variant you want to run               |
| `inputs`     | object  | No       | Key-value pairs for any prompt variables used by the prompt |
| `streaming`  | boolean | No       | Whether the response should be streamed                     |

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

Replace `YOUR_API_KEY`, `YOUR_DEPLOYMENT_NAME`, `YOUR_VARIANT_NAME`, and the `inputs` object with your real values.

## Response

If `streaming` is `true`, the API returns a stream of `data:` events rather than one final JSON object.

### Streaming response

You can receive different event types during the stream. For example:

Reasoning or thinking event:

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

Response event:

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

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

### Non-streaming response

If `streaming` is `false`, the API returns a single JSON response. For example:

```json
{
  "request_id": "req_019d528660dd7e22b15e5b13a1931c50",
  "model": "gpt-5-nano-2025-08-07",
  "duration": 4.641960144042969,
  "reasoning": "**Clarifying summary request**\n\nI need to follow up on the user's request for a 50-word summary since their message was incomplete. I should ask them to clarify the text or topic they'd like summarized. I can suggest options like pasting a passage or specifying a source. I’ll also mention I can summarize up to 50 words or suggest a different length if they prefer. Let’s get that response ready!",
  "response": "I’m missing the text or topic to summarize. Please paste the passage (or name the work) you want summarized, and I’ll provide exactly 50 words. If you prefer a different length, tell me the target word count. I can summarize articles, chapters, speeches, or any provided content.",
  "usage": {
    "prompt_tokens": {
      "total_tokens": 24,
      "cached_tokens": 0
    },
    "completion_tokens": {
      "total_tokens": 187,
      "reasoning_tokens": 64
    },
    "total_tokens": 211
  },
  "stop_reason": "completed"
}
```

## Next steps

* [Publishing and Versioning](https://docs.fetchhive.com/prompts/publishing-and-versioning)
* [Run with Python SDK](https://docs.fetchhive.com/prompts/run-with-python-sdk) - Python SDK docs are not available yet
* [Run with Node.js SDK](https://docs.fetchhive.com/prompts/run-with-nodejs-sdk) - Node.js SDK docs are not available yet