Skip to main content
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 endpoint, handles authentication, and supports both direct responses and callback delivery.

​
Installation

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: 
export FETCH_HIVE_API_KEY=fhk_...

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

const client = new FetchHive();
Or pass the key explicitly: 
const client = new FetchHive({ apiKey: 'fhk_...' });
See API Keys for how to create and rotate keys.

​
Basic example

Run a workflow deployment directly. The call blocks until the workflow finishes: 
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.

​
Method reference

FieldTypeRequiredDescription
deploymentstringYesThe workflow deployment name
variantstringNoThe deployment variant name
inputsRecord<string, unknown>NoKey-value pairs for the variables defined on the Start step
async{ enabled: boolean, callback_url?: string }NoCallback delivery settings
userstringNoOpaque caller identifier surfaced in User Tracking
metadataRecord<string, string | number | boolean | null>NoFlat caller-defined metadata for audit and log filtering. See Invoke metadata

​
Handling the response

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: 
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 for the verification flow and signed payload shape.

​
Configuration

OptionDefaultDescription
apiKeyprocess.env.FETCH_HIVE_API_KEYBearer token from the dashboard
baseURLhttps://api.fetchhive.com/v1Override the API base URL
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: 
try {
  const run = await client.invokeWorkflow({
    deployment: 'my-workflow',
    variant: 'default',
  });
} catch (err) {
  console.error('Fetch Hive error:', err);
}
See Error Handling for workflow-specific failure cases and Errors and Rate Limits for HTTP status code meanings.

​
Next steps