Setup

Installation & Configuration

Zero dependencies. Native fetch. ESM-only. Full TypeScript types.

Install

npm install @recursiv/sdk

Requirements:

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

Quick start

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

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

Configuration options

OptionTypeDefaultDescription
apiKeystringprocess.env.RECURSIV_API_KEYYour API key. Falls back to SOCIAL_DEV_API_KEY for backwards compatibility.
baseUrlstringhttps://api.recursiv.io/api/v1API base URL. Change this for self-hosted instances.
timeoutnumber30000Request timeout in milliseconds.
maxRetriesnumber2Number of retries on 429 and 5xx errors. Set to 0 to disable.
anonymousbooleanfalseEnable anonymous mode (no API key required, limited to sandbox).

Explicit configuration

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

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.

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

Self-hosted mode

Point the SDK at your own Recursiv instance:

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

Environment matrix

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

EnvironmentStatusNotes
Node.js >= 18Fully supportedNative fetch, no polyfills needed.
Next.jsFully supportedWorks in API routes, server components, middleware, and client components.
ReactFully supportedUse in useEffect or data-fetching libraries.
React Native / ExpoSupported with caveatsCore SDK works. chatStream() does not work due to missing ReadableStream. See the React Native guide for the workaround.
DenoFully supportedImport via npm:@recursiv/sdk.
BunFully supportedNative ESM and fetch support.
BrowserFully supportedBundle with Vite, esbuild, or webpack. API key should come from a backend proxy in production.

Node.js

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

Next.js (Server Component)

import { Recursiv } from '@recursiv/sdk';
export default async function Page() {
  const r = new Recursiv();
  const { data: projects } = await r.projects.list();
  return (
    <ul>
      {projects.map((p) => (
        <li key={p.id}>{p.name}</li>
      ))}
    </ul>
  );
}

Next.js (API Route)

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

Deno

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

Bun

import { Recursiv } from '@recursiv/sdk';
const r = new Recursiv();
const { data: me } = await r.users.me();
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:

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

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).

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