# Run with Node.js SDK

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/invoke-workflow.md) endpoint, handles authentication, and supports both synchronous and asynchronous runs.

## 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+ (uses the global `fetch`) and ships with TypeScript types.

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

Run a workflow deployment synchronously — the call blocks until the workflow finishes:

```typescript
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 [sync response shape](/api-reference/invoke-workflow.md#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       | Async run settings                                                                    |
| `user`       | `string`                                      | No       | Opaque caller identifier surfaced in [User Tracking](/user-tracking/user-tracking.md) |

## Handling the response

```typescript
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
```

## Async runs and webhooks

Pass an `async` block to queue the workflow and have Fetch Hive call your webhook when the run finishes:

```typescript
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 [Async and Webhooks](/workflows/async-and-webhooks.md) 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
const client = new FetchHive({
  apiKey: 'fhk_...',
  baseURL: 'https://api.fetchhive.com/v1',
});
```

For long-running synchronous workflows, 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
try {
  const run = await client.invokeWorkflow({
    deployment: 'my-workflow',
    variant: 'default',
  });
} catch (err) {
  console.error('Fetch Hive error:', err);
}
```

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

* [Async and Webhooks](/workflows/async-and-webhooks.md) - Verify callback signatures
* [Run with API](/workflows/run-with-api.md) - The same flow with cURL
* [Run with Python SDK](/workflows/run-with-python-sdk.md)
* [Run with Ruby SDK](/workflows/run-with-ruby-sdk.md)
* [Run with PHP SDK](/workflows/run-with-php-sdk.md)
* [Invoke Workflow](/api-reference/invoke-workflow.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/workflows/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.