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

> Start a Hive Agent run from Node.js or TypeScript with the @fetch-hive/sdk package

Use the official `@fetch-hive/sdk` package when you want to start a Hive Agent run from Node.js or TypeScript. The SDK wraps the public [`POST /v1/hive-agent/invoke`](../api-reference/hive-agents/invoke) endpoint with a typed client and handles authentication.

Hive Agent invocation does not stream and does not wait for the final answer in the HTTP response. The SDK returns identifiers immediately, then Fetch Hive sends a signed callback when the run completes, fails, or is cancelled.

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

Start a Hive Agent run and read the accepted response:

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

const client = new FetchHive();

const result = await client.invokeHiveAgent({
  hive_agent: 'YOUR_HIVE_AGENT_ID',
  objective: 'Research competitors and summarize verified findings',
  callback_url: 'https://example.com/hive-agent-callback',
  sources: {
    website_urls: ['https://example.com'],
  },
  metadata: { customer_id: 'cus_123' },
});

console.log(result.run_id);
console.log(result.request_id);
console.log(result.webhook_secret);
```

`invokeHiveAgent` returns a `Promise` that resolves to the parsed JSON body as soon as the run is queued. See the [accepted response shape](../api-reference/hive-agents/invoke#response).

## Method reference

| Field          | Type                                                                                                                   | Required | Description                                                                                                       |
| -------------- | ---------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `hive_agent`   | `string`                                                                                                               | Yes      | The Hive Agent ID from the dashboard                                                                              |
| `objective`    | `string`                                                                                                               | Yes      | Specific objective for the planner to create work nodes from                                                      |
| `callback_url` | `string`                                                                                                               | Yes      | HTTPS URL that receives the signed terminal callback                                                              |
| `sources`      | `{ website_urls?: string[]; asset_ids?: string[]; knowledge_base_ids?: string[]; knowledge_base_item_ids?: string[] }` | No       | Grounded context from websites, assets, or knowledge bases in the workspace                                       |
| `metadata`     | `Record<string, string \| number \| boolean \| null>`                                                                  | No       | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |

The SDK always sends `async.enabled: true` with your `callback_url`. Hive Agent invocation is async-only.

## Handling the response

Fetch Hive returns `202 Accepted` when the run is queued. Store `webhook_secret` so your callback receiver can verify `X-Fetch-Hive-Signature`.

```typescript theme={null}
const result = await client.invokeHiveAgent({
  hive_agent: 'YOUR_HIVE_AGENT_ID',
  objective: 'Research competitors and summarize verified findings',
  callback_url: 'https://example.com/hive-agent-callback',
});

console.log(result.run_id);          // queued run identifier
console.log(result.request_id);      // use this to look up the run in Logs
console.log(result.status);          // usually "pending"
console.log(result.webhook_secret);  // verify the signed callback
```

Open [Logs](./logs) to inspect status, trace, costs, node output, callback attempts, and the final response.

## 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',
});
```

## Errors

Missing `callback_url` throws before a request is sent. Non-2xx responses throw an `Error` whose message includes the status code and response body:

```typescript theme={null}
try {
  const result = await client.invokeHiveAgent({
    hive_agent: 'YOUR_HIVE_AGENT_ID',
    objective: 'Research competitors and summarize verified findings',
    callback_url: 'https://example.com/hive-agent-callback',
  });
} catch (err) {
  console.error('Fetch Hive error:', err);
}
```

See [Errors and Rate Limits](../api-reference/errors-and-rate-limits) 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

* [Invoke from Code](./invoke-from-code) - Overview of starting runs from your app
* [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](../api-reference/hive-agents/invoke) - Full endpoint reference