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:

1import { Recursiv } from '@recursiv/sdk';
2
3const 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.

1import { Recursiv } from '@recursiv/sdk';
2
3const r = new Recursiv();
4
5const { data: project } = await r.projects.create({ name: 'my-app' });
6
7await r.databases.ensure({ project_id: project.id, name: 'main' });
8
9const { data: result } = await r.databases.query({
10  project_id: project.id,
11  sql: 'SELECT NOW() as time',
12});
13
14console.log(project.id);
15console.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.

1import { Recursiv } from '@recursiv/sdk';
2
3const r = new Recursiv();
4
5const { data: agent } = await r.agents.create({
6  project_id: project.id,
7  name: 'Support Bot',
8  model: 'anthropic/claude-sonnet-4.6',
9  system_prompt: 'You are a helpful assistant.',
10});
11
12for await (const chunk of r.agents.chatStream(agent.id, {
13  message: 'Help me build a landing page',
14})) {
15  process.stdout.write(chunk.delta ?? '');
16}

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.

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

Where to go next