reclaim-sdk

Unofficial Node.js SDK for the Reclaim.ai API — tasks, habits, hours, webhooks and the changelog feed, all behind a single, fully-typed surface.

npm install reclaim-sdk

Requires Node 20 or newer. Zero runtime dependencies (uses the built-in fetch and node:crypto).

⚠️ This package is not affiliated with Reclaim.ai. It is reverse-engineered from the public web app plus the partial Swagger spec at https://api.app.reclaim.ai/swagger/reclaim-api-0.1.yml. The Reclaim API is not formally versioned for third-party use, so things may break without warning. Pin a version and watch the changelog.

---

Contents

• Quick start
• Configuration
• Tasks
• Daily habits
• Hours / time schemes
• Changelog feed
• Webhooks
• Errors
• Coverage matrix
• TypeScript
• Enum reference
• License
• Credits

---

Quick start

import { ReclaimClient, Task, PriorityLevel } from "reclaim-sdk";

ReclaimClient.configure({ token: process.env.RECLAIM_TOKEN! });

const task = new Task({
  title: "Write Q3 wrap-up",
  priority: PriorityLevel.P2,
  due: new Date("2026-09-30"),
});
task.duration = 2;            // 2h of work
task.minWorkDuration = 0.5;   // 30 min min slot
await task.save();

await task.start();
await task.logWork(45);       // log 45 minutes
await task.stop();
await task.markComplete();

reclaim-sdk ships in both ESM and CommonJS flavours with complete .d.ts types — import and require both work.

---

Configuration

Grab an API token from https://app.reclaim.ai/settings/developer.

Pick one of:

// Option A — pass it explicitly.
import { ReclaimClient } from "reclaim-sdk";
ReclaimClient.configure({ token: "rec_..." });

# Option B — set an env var; the SDK picks it up on first use.
export RECLAIM_TOKEN=rec_...

ReclaimClient is a singleton — call configure once at boot and every resource picks it up automatically. To override per-call (e.g. multi-tenant workers), pass a { client } option to any static method.

Custom base URL or fetch

ReclaimClient.configure({
  token: "rec_...",
  baseUrl: "https://api.app.reclaim.ai", // default
  fetch: customFetch,                     // optional — for tests / proxies
});

---

Tasks

Full CRUD against /api/tasks plus every planner action.

import { Task, PriorityLevel, EventColor } from "reclaim-sdk";

// List
const tasks = await Task.list();

// Fetch one
const t = await Task.get(12345);

// Create
const draft = new Task({
  title: "Migrate auth middleware",
  priority: PriorityLevel.P1,
  notes: "Per legal/compliance review",
});
draft.duration = 4;             // 4 hours, rounded to 15-min chunks
draft.eventColor = EventColor.GRAPE;
await draft.save();

// Update — patch only the touched fields
draft.notes = "Updated scope after standup";
await draft.save();

// Planner actions
await draft.start();
await draft.logWork(60);
await draft.stop();
await draft.markComplete();
await draft.markIncomplete();   // un-archive

await draft.snooze({ option: "TOMORROW" });
await draft.clearSnooze();

await draft.planWork({
  dateTime: new Date("2026-06-01T09:00:00Z"),
  durationMinutes: 90,
});
await draft.addTime(0.5);       // add 30 min

await draft.delete();

Batch operations

import { Task, type TaskPatch } from "reclaim-sdk";

const patches: TaskPatch[] = [
  { taskId: 11, patch: { priority: "P1" } },
  { taskId: 12, patch: { priority: "P2" } },
];
await Task.batchPatch(patches);
await Task.batchArchive(patches);
await Task.batchDelete(patches);

// One-shot reorder by due date:
const reordered = await Task.prioritizeByDue();

Pin to a specific start time

import { Task } from "reclaim-sdk";

const pinned = new Task({ title: "Pair-programming with @b", priority: "P2" });
pinned.duration = 1;
const result = await Task.createAtTime(pinned, new Date("2026-06-02T15:00:00Z"));

Time chunks

Reclaim's planner thinks in 15-minute increments. Use the human-friendly accessors:

Hours accessor	Underlying chunk field
duration	timeChunksRequired
minWorkDuration	minChunkSize
maxWorkDuration	maxChunkSize
upNext	onDeck

Setting an hours value rewrites the chunk count; reading it returns chunks / 4.

---

Daily habits

import { DailyHabit } from "reclaim-sdk";

const habits = await DailyHabit.list();

const focus = habits.find(h => h.title === "Deep work");
if (focus) {
  await focus.toggle(false);         // pause
  await focus.toggle(true);          // resume
}

// Habit templates (read-only catalogue)
const tpl = await DailyHabit.getTemplate();
const examples = await DailyHabit.listTemplates({ role: "engineer" });

Creating habits directly via API frequently returns 409 (calendar collisions, plan-tier limits). In practice, create habits in the web app and manage them — toggle / reschedule / skip — through the SDK.

---

Hours / time schemes

A time scheme is a named working-hours profile (/api/timeschemes). You can create custom schemes with per-weekday intervals and bind them to specific tasks or habits.

import { EventCategory, Hours, PolicyType, TimeSchemeFeature, Weekday } from "reclaim-sdk";

const workday = { intervals: [{ start: "09:00:00", end: "17:00:00" }] };

const scheme = new Hours({
  title: "Demo Hours",
  description: "Custom 9-5 Mon-Fri",
  taskCategory: EventCategory.WORK,
  policyType: PolicyType.CUSTOM,
  policy: {
    dayHours: {
      [Weekday.MONDAY]: workday,
      [Weekday.TUESDAY]: workday,
      [Weekday.WEDNESDAY]: workday,
      [Weekday.THURSDAY]: workday,
      [Weekday.FRIDAY]: workday,
    },
  },
  features: [
    TimeSchemeFeature.TASK_ASSIGNMENT,
    TimeSchemeFeature.HABIT_ASSIGNMENT,
  ],
});
await scheme.save();

// Bind a task to this scheme
const t = await Task.get(123);
t.timeSchemeId = scheme.id;
await t.save();

// Update
scheme.description = "Updated";
await scheme.save();

// Delete
await scheme.delete();

policyType: "CUSTOM" is required when you want to send your own policy.dayHours. The other policy values (WORK, PERSONAL, MEETING) bind the scheme to a user's main profile.

---

Changelog feed

A read-only stream of change events across Reclaim resources. Useful for polling sync workers.

import { Changelog, Task } from "reclaim-sdk";

// Everything
const all = await Changelog.all();

// Scoped to specific ids
const tasks = await Task.list();
const ids = tasks.slice(0, 5).map(t => t.id!).filter((v): v is number => !!v);
const taskEvents = await Changelog.tasks(ids);

// Other feeds
await Changelog.events(["abc", "def"]);
await Changelog.smartHabits([1, 2]);
await Changelog.smartMeetings([3, 4]);
await Changelog.schedulingLinks(["link-1", "link-2"]);

---

Webhooks

Subscribing

import { Webhook } from "reclaim-sdk";

// List existing subscriptions
for (const wh of await Webhook.list()) {
  console.log(wh.id, wh.url, wh.status, wh.events);
}

// Create a new one
const wh = new Webhook({
  url: "https://yourapp.example.com/reclaim-hook",
  events: ["task.created", "task.updated", "task.completed"],
  status: "ACTIVE",
  apiVersion: "v2026-04-13",
  name: "my-integration",
});
await wh.save();

Subscribing requires an apiVersion value. The webhook feature may need to be provisioned by Reclaim before POST succeeds — contact support if you see 500 errors on create.

Receiving

import express from "express";
import {
  parseWebhookPayload,
  verifySignature,
  isTaskWebhookEvent,
  isHabitWebhookEvent,
  SignatureVerificationError,
} from "reclaim-sdk";

const app = express();

app.post(
  "/reclaim-hook",
  express.raw({ type: "application/json" }),    // raw body, not parsed JSON
  (req, res) => {
    try {
      verifySignature(
        req.body,
        req.header("X-Reclaim-Signature"),
        process.env.RECLAIM_WEBHOOK_SECRET!,
      );
    } catch (err) {
      if (err instanceof SignatureVerificationError) return res.sendStatus(401);
      throw err;
    }

    const event = parseWebhookPayload(req.body);
    if (isTaskWebhookEvent(event)) {
      console.log("task", event.type, event.task.id, event.task.title);
    } else if (isHabitWebhookEvent(event)) {
      console.log("habit", event.type, event.habit.id, event.habit.title);
    }
    res.sendStatus(200);
  },
);

parseWebhookPayload rehydrates the inner task / habit field into a full Task / DailyHabit instance, so you can immediately call methods on it (e.g. event.task.markComplete()).

Always pass the raw body to verifySignature. Parsing and re-stringifying JSON changes whitespace and breaks the HMAC digest.

---

Errors

Every API failure throws a typed error. Catch the base class to handle them generically, or the subclass for fine-grained recovery:

import {
  ReclaimAPIError,
  RecordNotFound,
  InvalidRecord,
  AuthenticationError,
  SignatureVerificationError,
} from "reclaim-sdk";

try {
  await Task.get(99999999);
} catch (err) {
  if (err instanceof RecordNotFound)        // 404
    return null;
  if (err instanceof InvalidRecord)         // 400 / 422
    console.warn("bad payload", err.body);
  if (err instanceof AuthenticationError)   // 401
    process.exit(1);
  if (err instanceof ReclaimAPIError)       // anything else
    throw err;
}

Every ReclaimAPIError carries .status (the HTTP status code) and .body (the parsed error body, if any).

---

Coverage matrix

Resource	Supported
Tasks	CRUD, batch ops, planner actions (start/stop/snooze/plan-work/log-work/complete/add-time/reindex/…)
Daily habits	CRUD, toggle, reschedule / skip events, templates, smart-series migration
Hours / time schemes	Full CRUD, custom dayHours policies, features, target calendars
Webhooks	CRUD subscriptions, typed payloads, HMAC-SHA256 signature verification
Changelog	All feeds (tasks, events, smart habits, smart meetings, scheduling links, full feed)

Not yet covered — open a PR if you need them: Events, Calendars, Scheduling Links, One-on-Ones, Analytics, Focus Settings, Integrations, API-key management, Admin / delegated access.

---

TypeScript

The package is written in TypeScript and ships full .d.ts types. All enums are exported both as value namespaces and as type aliases so you can write priority: PriorityLevel.P1 or priority: "P1" interchangeably:

import { PriorityLevel } from "reclaim-sdk";

let p: PriorityLevel;
p = PriorityLevel.P1;   // ✓
p = "P2";               // ✓
p = "P5";               // ✗ — TS error

Init shapes

Each resource exports a matching *Init interface — useful for typing partial drafts you build up before saving:

import { type TaskInit, type WebhookEventName, Task } from "reclaim-sdk";

function buildTask(overrides: TaskInit): Task {
  return new Task({ title: "Default", priority: "P3", ...overrides });
}

const subscribedEvents: WebhookEventName[] = ["task.created", "habit.deleted"];

Available: TaskInit, DailyHabitInit, HoursInit, WebhookInit, WebhookEventName.

---

Enum reference

All enums are exported as const objects + matching string-literal type. Use either form interchangeably.

PriorityLevel

Task / habit priority bucket. Lower number = higher priority.

P1 · P2 · P3 · P4

EventCategory

Top-level category. Drives which working-hours profile the planner consults.

WORK · PERSONAL · BOTH

EventColor

Calendar event colour (mirrors Google Calendar's palette).

NONE · LAVENDER · SAGE · GRAPE · FLAMINGO · BANANA · TANGERINE · PEACOCK · GRAPHITE · BLUEBERRY · BASIL · TOMATO

EventSubType

Detailed event sub-category as understood by the scheduling engine.

ONE_ON_ONE · STAFF_MEETING · OP_REVIEW · EXTERNAL · IDEATION · FOCUS · PRODUCTIVITY · TRAVEL · FLIGHT · TRAIN · RECLAIM · VACATION · HEALTH · ERRAND · OTHER_PERSONAL · UNKNOWN

TaskStatus

Lifecycle state of a task. Read-only — set by the server.

NEW · SCHEDULED · IN_PROGRESS · COMPLETE · CANCELLED · ARCHIVED

TaskSource

Where a task originated. Reclaim's own tasks use RECLAIM; integrations carry their own value.

RECLAIM · GOOGLE · ASANA · CLICKUP · JIRA · TODOIST · LINEAR

SnoozeOption

Built-in snooze presets accepted by task.snooze({ option }) / habit.snooze({ option }). Combine with relativeFrom to shift the reference point away from "now".

Value	Meaning
FROM_NOW_15M	+15 minutes
FROM_NOW_30M	+30 minutes
FROM_NOW_1H	+1 hour
FROM_NOW_2H	+2 hours
FROM_NOW_4H	+4 hours
TOMORROW	next morning
IN_TWO_DAYS	the day after tomorrow
NEXT_WEEK	start of next week

import { SnoozeOption } from "reclaim-sdk";

await task.snooze({ option: SnoozeOption.TOMORROW });

// Custom reference point — snooze starts 2h after a given timestamp:
await task.snooze({
  option: SnoozeOption.FROM_NOW_2H,
  relativeFrom: new Date("2026-05-13T14:00:00Z"),
});

await task.clearSnooze();

Weekday

Used as the key type for TimeSchemePolicy.dayHours.

MONDAY · TUESDAY · WEDNESDAY · THURSDAY · FRIDAY · SATURDAY · SUNDAY

TimeSchemeFeature

Which Reclaim flows are allowed to consume a given time scheme.

Value	Used by
TASK_ASSIGNMENT	Tasks
HABIT_ASSIGNMENT	Daily habits
SMART_HABIT	Smart habits
ONE_ON_ONE_ASSIGNMENT	1:1 meetings
SMART_MEETING	Smart meetings
SCHEDULING_LINK_MEETING	Scheduling-link bookings

PolicyType

Time-scheme policy mode. CUSTOM is required to send your own policy.dayHours; the others bind the scheme to the user's main profile.

CUSTOM · WORK · PERSONAL · MEETING

---

License

MIT — see LICENSE.

---

Credits

Big thanks to the team behind the original labiso-gmbh/reclaim-sdk (Python) — the work they put into reverse-engineering the Reclaim API and keeping it documented made building alternative clients in other languages possible. If you also work in Python, go check it out.