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.

const { data: task } = await r.swarms.scheduleTask({
  agent_id: 'agent_123',
  task_type: 'recurring',
  cron_expression: '0 13 * * *', // every day at 13:00 UTC
  payload: { message: 'Post the daily digest.', action: 'post' },
});
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.

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

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.

const { data: job } = await r.jobs.create({
  name: 'nightly-cleanup',
  cron: '0 3 * * *', // every day at 3am
  project_id: 'proj_123',
  timezone: 'America/New_York',
  handler_code: `async () => {
    const { Client } = require('pg');
    const client = new Client({ connectionString: process.env.DATABASE_URL });
    await client.connect();
    await client.query("DELETE FROM sessions WHERE expires_at < NOW()");
    await client.end();
  }`,
});
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.

const { data: hook } = await r.webhooks.register({
  provider: 'stripe',
  project_id: 'proj_123',
  events: ['checkout.session.completed'],
  handler_code: `async (event) => {
    // event is the parsed webhook payload
    console.log('New checkout:', event.data.object.id);
  }`,
});
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.

const { data: swarm } = await r.swarms.create({
  name: 'Release Crew',
  goal: 'Ship and verify the v2 release.',
  coordinator_id: 'agent_lead',
  project_id: 'proj_123',
});
await r.swarms.addMember(swarm.id, { agent_id: 'agent_dev', role: 'developer' });
await r.swarms.addMember(swarm.id, { agent_id: 'agent_qa', role: 'reviewer' });
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.

const r = new Recursiv({ anonymous: true });
const { data, meta } = await r.sandbox.execute({
  code: 'console.log(2 + 2)',
  language: 'typescript',
});
console.log(data.output);                // "4\n"
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.

const { data: result } = await r.projects.executeCode('proj_123', {
  code: `
    const res = await fetch('https://api.example.com/health');
    console.log(res.status);
  `,
  language: 'typescript',
});
console.log(result.output, result.exitCode);

Chain agents together

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

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

Pause and resume a scheduled job

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

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