> ## 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 Node.js SDK

> Invoke a workflow deployment from Node.js or TypeScript with the @fetch-hive/sdk package

Use the official `@fetch-hive/sdk` package when you want to invoke a workflow deployment from Node.js or TypeScript. The SDK wraps the public [`POST /v1/workflow/invoke`](../api-reference/workflows/invoke) endpoint, handles authentication, and supports both direct responses and callback delivery.

## Installation

```bash theme={null}
npm install @fetch-hive/sdk
# or
yarn add @fetch-hive/sdk
# or
pnpm add @fetch-hive/sdk
```

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

## Authentication

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

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

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

const client = new FetchHive();
```

Or pass the key explicitly:

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

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

## Basic example

Run a workflow deployment directly. The call blocks until the workflow finishes:

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

const client = new FetchHive();

const run = await client.invokeWorkflow({
  deployment: 'YOUR_DEPLOYMENT_NAME',
  variant: 'YOUR_VARIANT_NAME',
  inputs: { topic: 'State of enterprise AI in 2026' },
});

console.log(run.status);
console.log(run.output);
```

See the [direct response shape](../api-reference/workflows/invoke#response).

## Method reference

| Field        | Type                                                  | Required | Description                                                                                                       |
| ------------ | ----------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `deployment` | `string`                                              | Yes      | The workflow deployment name                                                                                      |
| `variant`    | `string`                                              | No       | The deployment variant name                                                                                       |
| `inputs`     | `Record<string, unknown>`                             | No       | Key-value pairs for the variables defined on the **Start** step                                                   |
| `async`      | `{ enabled: boolean, callback_url?: string }`         | No       | Callback delivery settings                                                                                        |
| `user`       | `string`                                              | No       | Opaque caller identifier surfaced in [User Tracking](../user-tracking/overview)                                   |
| `metadata`   | `Record<string, string \| number \| boolean \| null>` | No       | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |

## Handling the response

```typescript theme={null}
const run = await client.invokeWorkflow({
  deployment: 'my-workflow',
  variant: 'default',
});

console.log(run.status);       // "completed" | "failed" | "running" | "queued"
console.log(run.output);       // final workflow output
console.log(run.request_id);   // use this to look up the run in Logs
```

## Callback delivery

Pass an `async` block to return immediately and have Fetch Hive call your callback URL when the run finishes:

```typescript theme={null}
const run = await client.invokeWorkflow({
  deployment: 'YOUR_DEPLOYMENT_NAME',
  variant: 'YOUR_VARIANT_NAME',
  inputs: { topic: 'State of enterprise AI in 2026' },
  async: { enabled: true, callback_url: 'https://example.com/callback' },
});

console.log('Queued:', run.status);
console.log('Webhook secret:', run.webhook_secret);
```

Store the `webhook_secret` so you can verify the signature on the incoming callback. See [Callback Delivery and Webhook Triggers](./async-and-webhooks) for the verification flow and signed payload shape.

## 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 theme={null}
const client = new FetchHive({
  apiKey: 'fhk_...',
  baseURL: 'https://api.fetchhive.com/v1',
});
```

For long-running direct workflow requests, prefer `async: { enabled: true, ... }` over increasing client-side timeouts.

## Errors

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

```typescript theme={null}
try {
  const run = await client.invokeWorkflow({
    deployment: 'my-workflow',
    variant: 'default',
  });
} catch (err) {
  console.error('Fetch Hive error:', err);
}
```

See [Error Handling](./error-handling) for workflow-specific failure cases and [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for HTTP 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

* [Callback Delivery and Webhook Triggers](./async-and-webhooks) - Verify callback signatures
* [Run with API](./run-with-api) - The same flow with cURL
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Ruby SDK](./run-with-ruby-sdk)
* [Run with PHP SDK](./run-with-php-sdk)
* [Invoke Workflow](../api-reference/workflows/invoke) - Full endpoint reference