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

# Run with Python SDK

> Invoke a prompt deployment from Python with the fetch-hive-sdk package

Use the official `fetch-hive-sdk` package when you want to invoke a prompt deployment from Python. The SDK wraps the public [`POST /v1/prompt/invoke`](../api-reference/prompts/invoke) endpoint with idiomatic helpers, handles authentication, and parses streaming responses for you.

## Installation

```bash theme={null}
pip install fetch-hive-sdk
```

The SDK requires Python 3.9+ and uses `httpx` under the hood.

## Authentication

Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key (the SDK reads it automatically):

```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```

```python theme={null}
from fetch_hive_sdk import FetchHive

client = FetchHive()
```

Or pass the key explicitly:

```python theme={null}
client = FetchHive(api_key="fhk_...")
```

See [API Keys](https://docs.fetchhive.com/workspace/api-keys.md) for how to create and rotate keys.

## Basic example

Invoke a prompt deployment and read the final response:

```python theme={null}
from fetch_hive_sdk import FetchHive

client = FetchHive()

result = client.invoke_prompt(
    deployment="YOUR_DEPLOYMENT_NAME",
    variant="YOUR_VARIANT_NAME",
    inputs={"text": "Fetch Hive helps teams ship AI products faster."},
)

print(result["response"])
```

`invoke_prompt` is synchronous and returns the parsed JSON body once the prompt has completed. See the [non-streaming response shape](https://docs.fetchhive.com/api-reference/prompts/invoke.md#response).

## Method reference

| Argument | Type | Required | Description |
| - | - | - | - |
| `deployment` | `str` | Yes | The prompt deployment name |
| `variant` | `str` | No | The deployment variant name |
| `inputs` | `dict[str, Any]` | No | Key-value pairs for the prompt variables |
| `user` | `str` | No | Opaque caller identifier surfaced in [User Tracking](https://docs.fetchhive.com/user-tracking/overview.md) |
| `metadata` | `dict[str, str \| int \| float \| bool \| None]` | No | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](https://docs.fetchhive.com/user-tracking/invoke-metadata.md) |

The SDK injects `streaming: false` for `invoke_prompt`. To stream, use `invoke_prompt_stream` (below).

## Handling the response

The non-streaming response is a plain `dict`:

```python theme={null}
result = client.invoke_prompt(deployment="my-prompt", variant="default")

print(result["response"])       # final text
print(result["model"])          # model identifier
print(result["usage"])          # token usage breakdown
print(result["request_id"])     # use this to look up the run in Logs
```

## Streaming

Use `invoke_prompt_stream` to receive Server-Sent Events as they arrive. The method returns a generator that yields parsed event dicts:

```python theme={null}
for chunk in client.invoke_prompt_stream(
    deployment="YOUR_DEPLOYMENT_NAME",
    variant="YOUR_VARIANT_NAME",
    inputs={"text": "Fetch Hive helps teams ship AI products faster."},
):
    if chunk.get("type") == "response":
        print(chunk.get("response", ""), end="", flush=True)
    elif chunk.get("type") == "usage":
        print("\n\nUsage:", chunk["usage"])
```

The stream yields the same event types documented in [Invoke Prompt → Response](https://docs.fetchhive.com/api-reference/prompts/invoke.md#response): `reasoning`, `response`, a final `usage` event, or an `error` event if the provider fails mid-stream.

### Async streaming

For `asyncio` applications, use `ainvoke_prompt_stream`. It has the same arguments but returns an async iterator:

```python theme={null}
import asyncio
from fetch_hive_sdk import FetchHive

async def main():
    client = FetchHive()
    async for chunk in client.ainvoke_prompt_stream(
        deployment="YOUR_DEPLOYMENT_NAME",
        variant="YOUR_VARIANT_NAME",
        inputs={"text": "Hello"},
    ):
        if chunk.get("type") == "response":
            print(chunk.get("response", ""), end="", flush=True)

asyncio.run(main())
```

## Configuration

| Option | Default | Description |
| - | - | - |
| `api_key` | `FETCH_HIVE_API_KEY` env var | Bearer token from the dashboard |
| `base_url` | `https://api.fetchhive.com/v1` | Override the API base URL |
| `timeout` | `120` | Request timeout in seconds |

```python theme={null}
client = FetchHive(
    api_key="fhk_...",
    base_url="https://api.fetchhive.com/v1",
    timeout=60,
)
```

## Errors

Non-2xx responses raise an `httpx.HTTPStatusError` with the status code and response body. Wrap calls in `try`/`except` if you need to handle failures:

```python theme={null}
import httpx

try:
    result = client.invoke_prompt(deployment="my-prompt", variant="default")
except httpx.HTTPStatusError as exc:
    print("Fetch Hive returned", exc.response.status_code, exc.response.text)
```

See [Errors and Rate Limits](https://docs.fetchhive.com/api-reference/errors-and-rate-limits.md) for status code meanings.

## Links

* [Package on PyPI](https://pypi.org/project/fetch-hive-sdk/)
* [Source on GitHub](https://github.com/Fetch-Hive/python-sdk)

## Next steps

* [Run with API](https://docs.fetchhive.com/prompts/run-with-api.md) - The same flow with cURL
* [Run with Node.js SDK](https://docs.fetchhive.com/prompts/run-with-nodejs-sdk.md)
* [Run with Ruby SDK](https://docs.fetchhive.com/prompts/run-with-ruby-sdk.md)
* [Run with PHP SDK](https://docs.fetchhive.com/prompts/run-with-php-sdk.md)
* [Invoke Prompt](https://docs.fetchhive.com/api-reference/prompts/invoke.md) - Full endpoint reference


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.