Skip to navigation
Connect

Connect Node.js

Install the SDK, configure your key, make your first authenticated call, and stream an agent

The @recursiv/sdk is a zero-dependency TypeScript SDK that runs server side in Node.js. This is the most direct way to script Recursiv, run backend services, or build agent workers.

Requirements

  • Node.js 18 or newer.
  • An ESM project ("type": "module" in package.json) for the import syntax below.

Install

npm install @recursiv/sdk

Configure the key

No account yet? Sign up and mint a key at recursiv.io/account/api-keys.

export RECURSIV_API_KEY=sk_live_...

The SDK reads RECURSIV_API_KEY automatically:

import { Recursiv } from '@recursiv/sdk';
const r = new Recursiv();

Or pass it explicitly with new Recursiv({ apiKey }).

First authenticated call

Most resources hang off a project. Create one, then run a query. Project IDs are UUIDs, so always use the id the API returns. Project-scoped calls return a { data } envelope.

import { Recursiv } from '@recursiv/sdk';
const r = new Recursiv();
const { data: project } = await r.projects.create({ name: 'my-app' });
await r.databases.ensure({ project_id: project.id, name: 'main' });
const { data: result } = await r.databases.query({
  project_id: project.id,
  sql: 'SELECT NOW() as time',
});
console.log(project.id);
console.log(result.rows);

Run and stream an agent

Create an agent against any model, then stream its replies. In Node, chatStream() returns an async iterable of { delta } chunks.

import { Recursiv } from '@recursiv/sdk';
const r = new Recursiv();
const { data: agent } = await r.agents.create({
  project_id: project.id,
  name: 'Support Bot',
  model: 'anthropic/claude-sonnet-4.6',
  system_prompt: 'You are a helpful assistant.',
});
for await (const chunk of r.agents.chatStream(agent.id, {
  message: 'Help me build a landing page',
})) {
  process.stdout.write(chunk.delta ?? '');
}

The model field is model agnostic. Pass any supported model id.

Run code in a sandbox

Node workers often need to execute generated code safely. The sandbox returns a { data, meta } envelope.

const { data } = await r.sandbox.execute({
  code: 'console.log(1 + 1)',
  language: 'typescript',
});
console.log(data.output); // "2\n"

Where to go next