> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recursiv.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recursiv.io/_mcp/server.

# Installation & Configuration

## Install

```bash
npm install @recursiv/sdk
```

**Requirements:**

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

## Quick start

```typescript
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

| 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

```typescript
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.

```typescript
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:

```typescript
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.

| 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](/sdk/platform/react-native) 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

```typescript
// 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)

```typescript
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)

```typescript
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

```typescript
import { Recursiv } from 'npm:@recursiv/sdk';

const r = new Recursiv();
const { data: me } = await r.users.me();
console.log(me);
```

### Bun

```typescript
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:

```typescript
// 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).

```typescript
// Disable retries entirely
const r = new Recursiv({ maxRetries: 0 });

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