Run with Node.js SDK

Use the official @fetch-hive/sdk package when you want to send a message to an agent from Node.js or TypeScript. The SDK wraps the public POST /v1/agent/invoke endpoint, handles authentication, exposes streaming as an AsyncIterable, and supports multimodal inputs.

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

Send a message to an agent and read the final response:

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

const client = new FetchHive();

const reply = await client.invokeAgent({
  agent: 'AGENT_UUID',
  message: 'Summarize the latest AI infrastructure trends',
});

console.log(reply.response);

See the non-streaming response shape.

Method reference

Field	Type	Required	Description
`agent`	`string`	Yes	The agent ID
`message`	`string`	Yes	The message you want to send
`thread_id`	`string`	No	An arbitrary string identifying a persistent conversation thread
`messages`	`Array<{ role, content, attachments? }>`	No	Caller-managed conversation history
`user`	`string`	No	Opaque caller identifier surfaced in User Tracking
`metadata`	`Record<string, string \| number \| boolean \| null>`	No	Flat caller-defined metadata for audit and log filtering. See Invoke metadata
`tool_approval`	`"policy" \| "auto_approve"`	No	Omit it, or send `"policy"`, to follow saved rules. `"auto_approve"` applies to this call only when the API key is allowed to auto-approve actions.

The SDK injects streaming: false for invokeAgent. To stream, use invokeAgentStream (below).

Handling the response

const reply = await client.invokeAgent({
  agent: 'AGENT_UUID',
  message: 'Hello',
});

console.log(reply.response);     // final text
console.log(reply.model);        // model identifier
console.log(reply.usage);        // token usage breakdown
console.log(reply.request_id);   // use this to look up the run in Logs
console.log(reply.tool_calls);   // tool invocations made during the run

Streaming

Use invokeAgentStream to receive Server-Sent Events as they arrive. The method returns an AsyncIterable:

for await (const chunk of client.invokeAgentStream({
  agent: 'AGENT_UUID',
  message: 'Summarize the latest AI infrastructure trends',
  thread_id: 'user-456-support-session',
})) {
  if (chunk.type === 'response') {
    process.stdout.write(chunk.response ?? '');
  } else if (chunk.type === 'tool') {
    console.log(`\n[Calling tool: ${chunk.tool}]`);
  } else if (chunk.type === 'usage') {
    console.log('\n\nUsage:', chunk.usage);
  }
}

The stream yields the same event types documented in Invoke Agent → Response: summary (when auto-summarization fires), reasoning, response, tool, a final usage event, or an error event if the provider fails mid-stream.

Multi-turn conversations

Persistent threads

Pass any string as thread_id and Fetch Hive will create the thread on the first call and resume it on subsequent calls with the same value:

await client.invokeAgent({
  agent: 'AGENT_UUID',
  message: 'What are the main AI infrastructure trends right now?',
  thread_id: 'user-456-support-session',
});

await client.invokeAgent({
  agent: 'AGENT_UUID',
  message: 'Which of those trends have the most enterprise adoption?',
  thread_id: 'user-456-support-session',
});

Stateless history

Manage state yourself by passing the previous turns in messages. Fetch Hive uses the supplied history for context but does not persist it:

await client.invokeAgent({
  agent: 'AGENT_UUID',
  message: 'Which of those trends have the most enterprise adoption?',
  messages: [
    { role: 'user', content: 'What are the main AI infrastructure trends right now?' },
    { role: 'assistant', content: 'Teams are focusing on evals, tool routing, and observability.' },
  ],
});

Multimodal inputs

Attach images to the current message with attachments:

const result = await client.invokeAgent({
  agent: 'vision-agent',
  message: 'Describe this image',
  attachments: ['https://example.com/photo.jpg'],
});
console.log(result.response);

URLs must start with https://.

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

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:

try {
  const reply = await client.invokeAgent({
    agent: 'AGENT_UUID',
    message: 'Hello',
  });
} catch (err) {
  console.error('Fetch Hive error:', err);
}

See Errors and Rate Limits for status code meanings.

Next steps

Run with API - The same flow with cURL
Run with Python SDK
Run with Ruby SDK
Run with PHP SDK
Invoke Agent - Full endpoint reference

Tool approvals

When a tool needs approval, the invoke response has status: "awaiting_approval" and pending_tool_approvals. Decide with decideToolActionApproval(workspaceId, approvalId, "allow_once") or "deny". List pending approvals with listToolActionApprovals, or fetch one with getToolActionApproval. always_allow is only available in the dashboard. An API key call resumes on the server after the decision. Poll the run or use the webhook. Do not send decided_tool_approvals. A workspace owner or admin can allow this API key to auto-approve actions in Settings → API keys. Pass tool_approval: "auto_approve" on invokeAgent, invokeAgentStream, or invokeWorkflow. That applies to this call only. Omit the field, or send "policy", to follow workspace rules and any saved auto-approve switch. Destructive actions still ask. Deny rules still block the action. See Tool approvals.

Getting Started

Live Chat

Prompts

Workflows

Hive Agents

Agents

Knowledge Bases

Your Workspace

Monitoring

User Tracking

MCP Gateway

Resources

Run with Node.js SDK

Installation

Authentication

Basic example

Method reference

Handling the response

Streaming

Multi-turn conversations

Persistent threads

Stateless history

Multimodal inputs

Configuration

Errors

Links

Next steps

Tool approvals

​Installation

​Authentication

​Basic example

​Method reference

​Handling the response

​Streaming

​Multi-turn conversations

​Persistent threads

​Stateless history

​Multimodal inputs

​Configuration

​Errors

​Links

​Next steps

​Tool approvals

Installation

Authentication

Basic example

Method reference

Handling the response

Streaming

Multi-turn conversations

Persistent threads

Stateless history

Multimodal inputs

Configuration

Errors

Links

Next steps

Tool approvals