Installation & Configuration

Install

$ npm install @recursiv/sdk

Requirements:

Node.js >= 18 (uses native fetch)
ESM only ("type": "module" in your package.json)
Zero dependencies

Quick start

1 import { Recursiv } from '@recursiv/sdk';
2 
3 const r = new Recursiv();
4 
5 const { data: projects } = await r.projects.list();
6 console.log(projects);

The zero-argument constructor reads your API key from the RECURSIV_API_KEY environment variable. No configuration file needed.

Configuration options

Option	Type	Default	Description
`apiKey`	`string`	`process.env.RECURSIV_API_KEY`	Your API key. Falls back to `SOCIAL_DEV_API_KEY` for backwards compatibility.
`baseUrl`	`string`	`https://api.recursiv.io/api/v1`	API base URL. Change this for self-hosted instances.
`timeout`	`number`	`30000`	Request timeout in milliseconds.
`maxRetries`	`number`	`2`	Number of retries on 429 and 5xx errors. Set to `0` to disable.
`anonymous`	`boolean`	`false`	Enable anonymous mode (no API key required, limited to sandbox).

Explicit configuration

1 import { Recursiv } from '@recursiv/sdk';
2 
3 const r = new Recursiv({
4   apiKey: 'sk_live_...',
5   baseUrl: 'https://api.recursiv.io/api/v1',
6   timeout: 30000,
7   maxRetries: 2,
8 });

Anonymous mode

For the anonymous sandbox (code execution without an account), pass anonymous: true. No API key is needed. Rate limited to 10 executions per day per IP.

1 import { Recursiv } from '@recursiv/sdk';
2 
3 const r = new Recursiv({ anonymous: true });
4 
5 const { data, meta } = await r.sandbox.execute({
6   code: 'console.log(1 + 1)',
7   language: 'typescript',
8 });
9 console.log(data.output); // "2\n"
10 console.log(`${meta.remaining_executions} executions remaining today`);

Self-hosted mode

Point the SDK at your own Recursiv instance:

1 const r = new Recursiv({
2   apiKey: 'sk_live_...',
3   baseUrl: 'https://my-instance.example.com/api/v1',
4 });

Environment matrix

The SDK uses the standard fetch API and works in any JavaScript runtime that supports it.

Environment	Status	Notes
Node.js >= 18	Fully supported	Native fetch, no polyfills needed.
Next.js	Fully supported	Works in API routes, server components, middleware, and client components.
React	Fully supported	Use in `useEffect` or data-fetching libraries.
React Native / Expo	Supported with caveats	Core SDK works. `chatStream()` does not work due to missing `ReadableStream`. See the React Native guide for the workaround.
Deno	Fully supported	Import via `npm:@recursiv/sdk`.
Bun	Fully supported	Native ESM and fetch support.
Browser	Fully supported	Bundle with Vite, esbuild, or webpack. API key should come from a backend proxy in production.

Node.js

1 // Set your API key in the environment
2 // RECURSIV_API_KEY=sk_live_... node index.mjs
3 
4 import { Recursiv } from '@recursiv/sdk';
5 const r = new Recursiv();

Next.js (Server Component)

1 import { Recursiv } from '@recursiv/sdk';
2 
3 export default async function Page() {
4   const r = new Recursiv();
5   const { data: projects } = await r.projects.list();
6 
7   return (
8     <ul>
9       {projects.map((p) => (
10         <li key={p.id}>{p.name}</li>
11       ))}
12     </ul>
13   );
14 }

Next.js (API Route)

1 import { Recursiv } from '@recursiv/sdk';
2 import { NextResponse } from 'next/server';
3 
4 export async function GET() {
5   const r = new Recursiv();
6   const { data: projects } = await r.projects.list();
7   return NextResponse.json(projects);
8 }

Deno

1 import { Recursiv } from 'npm:@recursiv/sdk';
2 
3 const r = new Recursiv();
4 const { data: me } = await r.users.me();
5 console.log(me);

Bun

1 import { Recursiv } from '@recursiv/sdk';
2 
3 const r = new Recursiv();
4 const { data: me } = await r.users.me();
5 console.log(me);

API key security

Never expose your API key in client-side code shipped to browsers. For browser-based apps, proxy requests through your backend:

1 // Backend (Node.js / Next.js API route)
2 import { Recursiv } from '@recursiv/sdk';
3 
4 const r = new Recursiv(); // reads RECURSIV_API_KEY from server env
5 
6 export async function GET(req: Request) {
7   const { data } = await r.posts.list({ limit: 20 });
8   return Response.json(data);
9 }

Auto-retry behavior

The SDK automatically retries failed requests when it receives:

429 Too Many Requests — respects the Retry-After header if present
5xx Server Errors — transient server failures

Retries use exponential backoff: 1s, 2s, 4s, … capped at 10s. The maxRetries option controls how many retries are attempted (default: 2).

1 // Disable retries entirely
2 const r = new Recursiv({ maxRetries: 0 });
3 
4 // More aggressive retries
5 const r = new Recursiv({ maxRetries: 5 });