The Tasks API lists, creates, updates, and deletes your Opal tasks. A task needs a title and a date. List tasks by date (today by default, in UTC) or by completion, and link a task to an item with linkedItem. Tasks are returned as { id, title, completed, date, notes, linkedItem, created, modified }.
List Tasks
GET /api/v1/tasks
| Parameter | Default | Notes |
|---|---|---|
date | today (UTC) | YYYY-MM-DD, or all for every date. |
completed | none | true or false (400 otherwise). Omit for all. |
limit | 100 | Max 1000. |
offset | 0 | Pagination offset. |
curl "https://app.opalrecall.com/api/v1/tasks?date=2026-10-12&completed=false" \ -H "Authorization: Bearer opal_live_xxx"
Returns { "data": { "tasks": [...], "total": n, "limit": n, "offset": n } }.
Get a Task
GET /api/v1/tasks/:taskId
Owner-only.
Create a Task
POST /api/v1/tasks
curl -X POST https://app.opalrecall.com/api/v1/tasks \
-H "Authorization: Bearer opal_live_xxx" \
-H "Content-Type: application/json" \
-d '{"title":"Review API docs","date":"2026-10-12","notes":"Optional notes","linkedItem":"ITEM_ID"}'
title and date are required. notes and linkedItem are optional. Returns 201 with the task under data.
Update or Complete a Task
PATCH /api/v1/tasks/:taskId
curl -X PATCH https://app.opalrecall.com/api/v1/tasks/TASK_ID \
-H "Authorization: Bearer opal_live_xxx" \
-H "Content-Type: application/json" \
-d '{"completed":true}'
Patchable fields: title, completed, notes, linkedItem, date, and toggled (whether the notes are expanded). Adding notes expands them unless you send toggled. Owner-only.
Link a Task to an Item
Set linkedItem when you create the task, or later with PATCH. Tasks store linkedItem as given, so send the item’s submission ID. See API Conventions: IDs, Response Format, and Status Codes.
Delete a Task
DELETE /api/v1/tasks/:taskId
Owner-only. Returns { "data": { "success": true } }.
Next Steps
- Find the item to link: Search API: Find Items by Title, Description, and Content or Items API: List, Get, Create, Update, and Delete
- See IDs and responses: API Conventions: IDs, Response Format, and Status Codes
- Handle limits: Errors, Rate Limits, and Plan Limits in the Opal API
FAQ
How do I list today’s tasks through the API?
Call GET /tasks with no parameters. date defaults to today in UTC. Use date=all for every date.
How do I mark a task complete?
Send PATCH /tasks/:taskId with {"completed": true}.
How many tasks can one request return?
limit defaults to 100 and has a maximum of 1000. Use offset to page.
Which ID do I use for linkedItem?
The item’s submission ID. Tasks store linkedItem as given.
