> ## Documentation Index
> Fetch the complete documentation index at: https://developer.folk.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrate from reminders to tasks
Reminders are deprecated in favor of Tasks (see the [changelog](/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 deal — plus capabilities reminders never had: a markdown `description`, richer filtering (see [List tasks](#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](/api-reference/tasks/mark-a-task-as-done) or
[Mark a task as to do](/api-reference/tasks/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](/api-reference/reminders/list-reminders) | [List tasks](/api-reference/tasks/list-tasks) |
| [Get a reminder](/api-reference/reminders/get-a-reminder) | [Get a task](/api-reference/tasks/get-a-task) |
| [Create a reminder](/api-reference/reminders/create-a-reminder) | [Create a task](/api-reference/tasks/create-a-task) |
| [Update a reminder](/api-reference/reminders/update-a-reminder) | [Update a task](/api-reference/tasks/update-a-task) |
| [Delete a reminder](/api-reference/reminders/delete-a-reminder) | [Delete a task](/api-reference/tasks/delete-a-task) |
| *(no equivalent — reminders don't track completion)* | [Mark a task as done](/api-reference/tasks/mark-a-task-as-done), [Mark a task as to do](/api-reference/tasks/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](#create-a-task-with-a-description). |
| `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
```http Tasks theme={null}
POST /v1/tasks
{
"title": "Send contract redline to Sarah Chen",
"entity": { "id": "per_55175e81-9a52-4ac3-930e-82792c23499b" },
"dueAt": "2025-07-17",
"isPublic": false
}
```
```http Reminders theme={null}
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
```http Tasks theme={null}
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" }]
}
```
```http Reminders theme={null}
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:
```http theme={null}
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:
```http Tasks theme={null}
GET /v1/tasks?filter[entity][in]=per_55175e81-9a52-4ac3-930e-82792c23499b
```
```http Reminders theme={null}
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:
```http theme={null}
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:
```http theme={null}
GET /v1/tasks?filter[dueAt][gt]=2025-07-01&filter[dueAt][lt]=2025-07-31
```
See the [filtering reference](/api-reference/filtering#filterable-fields-for-tasks) for the full list of task filters.
### Update a task
Renaming and rescheduling maps directly:
```http Tasks theme={null}
PATCH /v1/tasks/tsk_91118b73-5a75-480b-b8e3-a33671c35cdc
{ "title": "Send contract redline to Sarah Chen", "dueAt": "2025-07-24" }
```
```http Reminders theme={null}
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:
```http theme={null}
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:
```http theme={null}
PATCH /v1/tasks/tsk_91118b73-5a75-480b-b8e3-a33671c35cdc
{ "entity": { "id": "com_f3855422-6740-4e6a-aa5e-449ac77047d0" } }
```