# Run with Node.js SDK

Use the official `@fetch-hive/sdk` package when you want to invoke a prompt deployment from Node.js or TypeScript. The SDK wraps the public [`POST /v1/invoke`](/api-reference/invoke-prompt.md) endpoint with a typed client, handles authentication, and exposes streaming as an `AsyncIterable`.

## Installation

```bash
npm install @fetch-hive/sdk
# or
yarn add @fetch-hive/sdk
# or
pnpm add @fetch-hive/sdk
```

The SDK targets Node.js 18+ (it uses the global `fetch`) and ships with TypeScript types out of the box.

## Authentication

Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key:

```bash
export FETCH_HIVE_API_KEY=fhk_...
```

```typescript
import { FetchHive } from '@fetch-hive/sdk';

const client = new FetchHive();
```

Or pass the key explicitly:

```typescript
const client = new FetchHive({ apiKey: 'fhk_...' });
```

See [API Keys](/your-workspace/api-keys.md) for how to create and rotate keys.

## Basic example

Invoke a prompt deployment and read the final response:

```typescript
import { FetchHive } from '@fetch-hive/sdk';

const client = new FetchHive();

const result = await client.invokePrompt({
  deployment: 'YOUR_DEPLOYMENT_NAME',
  variant: 'YOUR_VARIANT_NAME',
  inputs: { text: 'Fetch Hive helps teams ship AI products faster.' },
});

console.log(result.response);
```

`invokePrompt` returns a `Promise` that resolves to the parsed JSON body once the prompt has completed. See the [non-streaming response shape](/api-reference/invoke-prompt.md#response).

## Method reference

| Field        | Type                      | Required | Description                                                                           |
| ------------ | ------------------------- | -------- | ------------------------------------------------------------------------------------- |
| `deployment` | `string`                  | Yes      | The prompt deployment name                                                            |
| `variant`    | `string`                  | No       | The deployment variant name                                                           |
| `inputs`     | `Record<string, unknown>` | No       | Key-value pairs for the prompt variables                                              |
| `user`       | `string`                  | No       | Opaque caller identifier surfaced in [User Tracking](/user-tracking/user-tracking.md) |

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

## Handling the response

```typescript
const result = await client.invokePrompt({
  deployment: 'my-prompt',
  variant: 'default',
});

console.log(result.response);     // final text
console.log(result.model);        // model identifier
console.log(result.usage);        // token usage breakdown
console.log(result.request_id);   // use this to look up the run in Logs
```

## Streaming

Use `invokePromptStream` to receive Server-Sent Events as they arrive. The method returns an `AsyncIterable` that you can consume with `for await`:

```typescript
for await (const chunk of client.invokePromptStream({
  deployment: 'YOUR_DEPLOYMENT_NAME',
  variant: 'YOUR_VARIANT_NAME',
  inputs: { text: 'Fetch Hive helps teams ship AI products faster.' },
})) {
  if (chunk.type === 'response') {
    process.stdout.write(chunk.response ?? '');
  } else if (chunk.type === 'usage') {
    console.log('\n\nUsage:', chunk.usage);
  }
}
```

The stream yields the same event types documented in [Invoke Prompt → Response](/api-reference/invoke-prompt.md#response): `reasoning`, `response`, and a final `usage` event.

## Configuration

| Option    | Default                          | Description                     |
| --------- | -------------------------------- | ------------------------------- |
| `apiKey`  | `process.env.FETCH_HIVE_API_KEY` | Bearer token from the dashboard |
| `baseURL` | `https://api.fetchhive.com/v1`   | Override the API base URL       |

```typescript
const client = new FetchHive({
  apiKey: 'fhk_...',
  baseURL: 'https://api.fetchhive.com/v1',
});
```

## Errors

Non-2xx responses throw an `Error` whose message includes the status code and response body:

```typescript
try {
  const result = await client.invokePrompt({
    deployment: 'my-prompt',
    variant: 'default',
  });
} catch (err) {
  console.error('Fetch Hive error:', err);
}
```

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

## Links

* [Package on npm](https://www.npmjs.com/package/@fetch-hive/sdk)
* [Source on GitHub](https://github.com/Fetch-Hive/nodejs-sdk)

## Next steps

* [Run with API](/prompts/run-with-api.md) - The same flow with cURL
* [Run with Python SDK](/prompts/run-with-python-sdk.md)
* [Run with Ruby SDK](/prompts/run-with-ruby-sdk.md)
* [Run with PHP SDK](/prompts/run-with-php-sdk.md)
* [Invoke Prompt](/api-reference/invoke-prompt.md) - Full endpoint reference


---

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