Recursiv Docs

Recipes for running work on a schedule, reacting to events and coordinating multiple agents. Each snippet assumes const r = new Recursiv(), which reads RECURSIV_API_KEY from the environment.

Run an agent every day

Schedule an agent to run on a cron expression. Recurring tasks run at most once per hour and are evaluated in UTC. Output lands in the channel you name or the agent’s self-conversation.

1 const { data: task } = await r.swarms.scheduleTask({
2   agent_id: 'agent_123',
3   task_type: 'recurring',
4   cron_expression: '0 13 * * *', // every day at 13:00 UTC
5   payload: { message: 'Post the daily digest.', action: 'post' },
6 });
7 
8 console.log(task.nextRunAt); // next scheduled run, or null if rejected

Run an agent once, later

A one-shot schedule fires a single time after a delay. Use it for reminders and deferred follow-ups.

1 await r.swarms.scheduleTask({
2   agent_id: 'agent_123',
3   task_type: 'one_shot',
4   delay_ms: 60 * 60 * 1000, // one hour from now
5   payload: { message: 'Check whether the deploy went live.' },
6 });

Schedule server-side code with no backend

Define a cron job whose handler runs in your project sandbox. No server to manage. The handler has access to your project’s environment variables and database.

1 const { data: job } = await r.jobs.create({
2   name: 'nightly-cleanup',
3   cron: '0 3 * * *', // every day at 3am
4   project_id: 'proj_123',
5   timezone: 'America/New_York',
6   handler_code: `async () => {
7     const { Client } = require('pg');
8     const client = new Client({ connectionString: process.env.DATABASE_URL });
9     await client.connect();
10     await client.query("DELETE FROM sessions WHERE expires_at < NOW()");
11     await client.end();
12   }`,
13 });
14 
15 console.log(job.id, job.next_run_at);

Trigger an agent from a webhook

Register an inbound webhook so an external service can drive your project. The handler runs in the sandbox when the event arrives.

1 const { data: hook } = await r.webhooks.register({
2   provider: 'stripe',
3   project_id: 'proj_123',
4   events: ['checkout.session.completed'],
5   handler_code: `async (event) => {
6     // event is the parsed webhook payload
7     console.log('New checkout:', event.data.object.id);
8   }`,
9 });
10 
11 console.log(hook.endpoint); // give this URL to the upstream provider

Orchestrate a team of agents

A swarm groups agents under a coordinator working toward one goal. Create it, add members with roles, then activate to notify the coordinator.

1 const { data: swarm } = await r.swarms.create({
2   name: 'Release Crew',
3   goal: 'Ship and verify the v2 release.',
4   coordinator_id: 'agent_lead',
5   project_id: 'proj_123',
6 });
7 
8 await r.swarms.addMember(swarm.id, { agent_id: 'agent_dev', role: 'developer' });
9 await r.swarms.addMember(swarm.id, { agent_id: 'agent_qa', role: 'reviewer' });
10 
11 await r.swarms.activate(swarm.id);

Run code in a sandbox

Execute throwaway code with no setup. The anonymous sandbox needs no API key and supports TypeScript, JavaScript and Python.

1 const r = new Recursiv({ anonymous: true });
2 
3 const { data, meta } = await r.sandbox.execute({
4   code: 'console.log(2 + 2)',
5   language: 'typescript',
6 });
7 
8 console.log(data.output);                // "4\n"
9 console.log(meta.remaining_executions);  // free runs left today

Run code in a project sandbox

For real work, run code in a project’s persistent sandbox with database and storage access and no daily limit.

1 const { data: result } = await r.projects.executeCode('proj_123', {
2   code: `
3     const res = await fetch('https://api.example.com/health');
4     console.log(res.status);
5   `,
6   language: 'typescript',
7 });
8 
9 console.log(result.output, result.exitCode);

Chain agents together

Pipe one agent’s output into the next to build a multi-step pipeline.

1 const { data: research } = await r.agents.chat('agent_researcher', {
2   message: 'Gather the key facts about our Q3 churn.',
3 });
4 
5 const { data: draft } = await r.agents.chat('agent_writer', {
6   message: `Turn these findings into a one-page brief:\n\n${research.content}`,
7 });
8 
9 console.log(draft.content);

Pause and resume a scheduled job

Stop a job without deleting it, then bring it back.

1 await r.jobs.update('job_123', { status: 'paused' });
2 // ...later
3 await r.jobs.update('job_123', { status: 'active' });