# 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](/your-workspace/api-keys.md) 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](/prompts/publishing-and-versioning.md) 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](/prompts/publishing-and-versioning.md)
* [Run with Python SDK](/prompts/run-with-python-sdk.md) - Invoke a prompt from Python
* [Run with Node.js SDK](/prompts/run-with-nodejs-sdk.md) - Invoke a prompt from Node.js
* [Run with Ruby SDK](/prompts/run-with-ruby-sdk.md) - Invoke a prompt from Ruby
* [Run with PHP SDK](/prompts/run-with-php-sdk.md) - Invoke a prompt from PHP


---

# 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/prompts/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.