Skip to navigation
Connect

Connect Next.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 in Server Components, API routes, and Client Components. This guide gets a Next.js app from install to a streaming agent.

Install

npm install @recursiv/sdk

Configure the key

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

Keep the key server side. Put it in .env.local:

RECURSIV_API_KEY=sk_live_...

The SDK reads RECURSIV_API_KEY automatically, so on the server you can just do new Recursiv(). You can also pass the key explicitly:

import { Recursiv } from '@recursiv/sdk';
const r = new Recursiv({ apiKey: process.env.RECURSIV_API_KEY });

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.

// app/api/setup/route.ts
import { Recursiv } from '@recursiv/sdk';
export async function POST() {
  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',
  });
  return Response.json({ project: project.id, rows: result.rows });
}

Run and stream an agent

Create an agent against any model, then stream its replies. In Node and the browser use chatStream(), which yields an async iterable of { delta } chunks.

// app/api/chat/route.ts
import { Recursiv } from '@recursiv/sdk';
export async function POST(req: Request) {
  const { agentId, message } = await req.json();
  const r = new Recursiv();
  const encoder = new TextEncoder();
  const stream = new ReadableStream({
    async start(controller) {
      for await (const chunk of r.agents.chatStream(agentId, { message })) {
        controller.enqueue(encoder.encode(chunk.delta ?? ''));
      }
      controller.close();
    },
  });
  return new Response(stream, {
    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
  });
}

Create the agent once (in setup, a script, or the dashboard):

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.',
});

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

Where to go next