Migrate from reminders to tasks

Reminders are deprecated in favor of Tasks (see the changelog). Reminders will keep working until February 11, 2027, but we recommend migrating as soon as possible. Tasks cover everything reminders did — linking a due date and optional recurrence to a person, company or object — plus capabilities reminders never had: a markdown description, richer filtering (see List tasks below), and completion tracking.

Completion is always a deliberate action. Unlike a reminder, which fires and is stamped as triggered automatically on its own schedule, a task’s completedAt only changes when a user (or your integration) explicitly calls Mark a task as done or Mark a task as to do. folk never marks a task as done or to do on its own.

Endpoint mapping

Reminders	Tasks
List reminders	List tasks
Get a reminder	Get a task
Create a reminder	Create a task
Update a reminder	Update a task
Delete a reminder	Delete a task
(no equivalent — reminders don’t track completion)	Mark a task as done, Mark a task as to do — always called explicitly, never automatic

Field mapping

Reminder field	Task field	Notes
`name`	`title`	Same purpose, renamed.
(no reminder equivalent)	`description`	New on tasks: free text in markdown format. See the example below.
`recurrenceRule` (time component of `DTSTART`)	`dueAt` / `dueTime`	Reminders embedded the time of day inside `recurrenceRule`’s `DTSTART`. Tasks split this out: `dueAt` is the due date, `dueTime` (`"HH:mm"` string, optional) is the time of day.
`recurrenceRule` (iCalendar `DTSTART`/`RRULE` string)	`recurrenceFrequency` (enum)	Tasks use a simple enum (`weekday`, `weekly`, `biweekly`, `monthly`, `quarterly`, `yearly`) driven by `dueAt`, instead of an iCalendar string with its own start time and timezone.
`visibility` (`"public"` / `"private"`)	`isPublic` (boolean)	`public` → `true` (visible to all workspace members), `private` → `false` (visible only to its assigned users).
`assignedUsers`	`assignedUsers`	Same shape (`id` or `email`). On reminders these are notified when the reminder fires; on tasks they’re the task’s owners.
`nextTriggerTime` / `lastTriggerTime`	`dueAt` / `completedAt`	Reminders compute the next/last fire time automatically from the recurrence rule, and are stamped as triggered as part of that automatic cycle. Tasks have a single `dueAt` you set directly, and `completedAt` only changes when a user explicitly calls mark-done or mark-todo — never automatically.

Examples

Create a task

Create a one-off task

POST /v1/tasks
{
  "title": "Send contract redline to Sarah Chen",
  "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b" },
  "dueAt": "2025-07-17",
  "isPublic": false
}

POST /v1/reminders
{
  "name": "Send contract redline to Sarah Chen",
  "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b" },
  "recurrenceRule": "DTSTART;TZID=Europe/Paris:20250717T090000\nRRULE:COUNT=1",
  "visibility": "private"
}

Create a recurring task

POST /v1/tasks
{
  "title": "Weekly pipeline review with Sarah Chen",
  "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b" },
  "dueAt": "2025-07-17",
  "recurrenceFrequency": "weekly",
  "isPublic": true,
  "assignedUsers": [{ "email": "sarah.chen@northwindtraders.com" }]
}

POST /v1/reminders
{
  "name": "Weekly pipeline review with Sarah Chen",
  "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b" },
  "recurrenceRule": "DTSTART;TZID=Europe/Paris:20250717T090000\nRRULE:FREQ=WEEKLY;INTERVAL=1",
  "visibility": "public",
  "assignedUsers": [{ "email": "sarah.chen@northwindtraders.com" }]
}

Create a task with a description

Tasks support a description field in markdown, which reminders never had:

POST /v1/tasks
{
  "title": "Send contract redline to Sarah Chen",
  "entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b" },
  "dueAt": "2025-07-17",
  "description": "**Before sending:**\n- Confirm the 10% discount matches what Finance approved\n- Have Legal review the liability clause (section 4.2)\n\nRedline draft: [Google Doc](https://docs.google.com/document/d/1a2b3c)",
  "isPublic": true
}

List tasks

Listing by entity maps directly:

GET /v1/tasks?filter[entity][in]=per_55175e81-9a52-4ac3-930e-82792c23499b

GET /v1/reminders?entity.id=per_55175e81-9a52-4ac3-930e-82792c23499b

Reminders can only be listed by entity. Tasks support much richer filtering — for example, listing overdue tasks that are still open and assigned to a specific user has no reminders equivalent at all:

GET /v1/tasks?filter[dueAt][lt]=2025-07-17&filter[completedAt][empty]&filter[assigneeUserId][in]=usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c

Or listing every task due in a given month, regardless of who it’s assigned to:

GET /v1/tasks?filter[dueAt][gt]=2025-07-01&filter[dueAt][lt]=2025-07-31

See the filtering reference for the full list of task filters.

Update a task

Renaming and rescheduling maps directly:

PATCH /v1/tasks/tsk_91118b73-5a75-480b-b8e3-a33671c35cdc
{ "title": "Send contract redline to Sarah Chen", "dueAt": "2025-07-24" }

PATCH /v1/reminders/rmd_91118b73-5a75-480b-b8e3-a33671c35cdc
{ "name": "Send contract redline to Sarah Chen", "recurrenceRule": "DTSTART;TZID=Europe/Paris:20250724T090000\nRRULE:COUNT=1" }

Marking work complete is a separate call, not a PATCH — and, as above, only ever happens because someone explicitly asked for it:

POST /v1/tasks/tsk_91118b73-5a75-480b-b8e3-a33671c35cdc/mark-done
{ "completedAt": "2025-07-24T15:32:00.000Z" }

Moving a task to a different entity is also new — reminders don’t support changing their linked entity at all, you’d have to delete and recreate one:

PATCH /v1/tasks/tsk_91118b73-5a75-480b-b8e3-a33671c35cdc
{ "entity": { "id": "com_f3855422-6740-4e6a-aa5e-449ac77047d0" } }

Webhooks

Reminder events are deprecated too and will be removed on February 13, 2027. A change to a task, in the folk app or through the Tasks endpoints, triggers both the reminder event and the task event, so you can subscribe to the task events first, then remove the reminder events from your webhook.

Reminder event	Task event
`reminder.created`	`task.created`
`reminder.updated`	`task.updated`, or `task.completed` when a task is marked as done
`reminder.deleted`	`task.deleted`
`reminder.triggered`	(no equivalent — tasks don’t fire on their own schedule)

Task events carry task IDs (tsk_), task URLs (/v1/tasks/:taskId) and task field names in their changes, as listed in the field mapping above.

Get started

Core concepts

Use cases

Webhooks

Migrations

Endpoint mapping

Field mapping

Examples

Create a task

Create a one-off task

Create a recurring task

Create a task with a description

List tasks

Update a task

Webhooks

​Endpoint mapping

​Field mapping

​Examples

​Create a task

​Create a one-off task

​Create a recurring task

​Create a task with a description

​List tasks

​Update a task

​Webhooks

Endpoint mapping

Field mapping

Examples

Create a task

Create a one-off task

Create a recurring task

Create a task with a description

List tasks

Update a task

Webhooks