Tasks API.
Manage tasks programmatically.
The Tasks API allows you to create, manage, and track tasks in Clear Tangle. Tasks can be manually created or automatically extracted from captures. Support for recurring tasks, priorities, and project organization is included.
Endpoints
METHODENDPOINTDESCRIPTION
GET/tasksList all tasks
POST/tasksCreate a task
GET/tasks/:idGet a task
PATCH/tasks/:idUpdate a task
DELETE/tasks/:idDelete a task
POST/tasks/:id/completeMark task complete
POST/tasks/:id/uncompleteMark task incomplete
GET/tasks/todayGet tasks due today
GET/tasks/overdueGet overdue tasks
Task object
A task object contains the following properties:
FIELDTYPEDESCRIPTION
idstringUnique task identifiertitlestringTask titledescriptionstringOptional detailed descriptionstatusstringpending, completed, or cancelleddueDateISO8601Due date and timeprioritystringlow, medium, high, or urgentprojectIdstringAssociated project IDtagsstring[]Array of tagsestimatedMinutesintegerEstimated time to completesourceCapturestringID of capture task was extracted fromrecurrenceobjectRecurrence configurationcompletedAtISO8601Completion timestampCreate a task
Create a new task with optional recurrence settings.
Create task · bash
curl -X POST "https://api.cleartangle.com/tasks" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Review Q1 budget proposal",
"description": "Go through the finance team proposal and provide feedback",
"dueDate": "2024-01-20T17:00:00Z",
"priority": "high",
"projectId": "proj_123456",
"tags": ["finance", "urgent"],
"estimatedMinutes": 45,
"recurrence": {
"frequency": "weekly",
"daysOfWeek": ["monday"]
}
}'
Response
Response · json
{
"success": true,
"data": {
"id": "task_abc123",
"title": "Review Q1 budget proposal",
"description": "Go through the finance team proposal and provide feedback",
"status": "pending",
"dueDate": "2024-01-20T17:00:00Z",
"priority": "high",
"projectId": "proj_123456",
"tags": ["finance", "urgent"],
"estimatedMinutes": 45,
"recurrence": {
"frequency": "weekly",
"daysOfWeek": ["monday"]
},
"sourceCapture": null,
"completedAt": null,
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
}
Recurring tasks
Set up recurring tasks with the recurrence object:
Daily
{ "frequency": "daily" }Weekly
{ "frequency": "weekly", "daysOfWeek": ["monday", "wednesday", "friday"] }Monthly
{ "frequency": "monthly", "dayOfMonth": 15 }Custom
{ "frequency": "custom", "intervalDays": 3 }RECURRING TASK BEHAVIOR
When a recurring task is completed, a new instance is automatically created for the next occurrence.
List tasks
Retrieve tasks with optional filtering.
List tasks · bash
curl -X GET "https://api.cleartangle.com/tasks?status=pending&priority=high&dueDate=2024-01-20" \
-H "Authorization: Bearer YOUR_API_KEY"
Query parameters
PARAMETERDESCRIPTION
statusFilter by status (pending, completed, cancelled)priorityFilter by priority (low, medium, high, urgent)projectIdFilter by projecttagsComma-separated tag filterdueDateFilter by due date (exact or range with startDate/endDate)overdueSet to true to only show overdue taskssortSort field (dueDate, priority, createdAt)orderSort order (asc, desc)Complete a task
Mark a task as completed with optional completion notes.
Complete task · bash
curl -X POST "https://api.cleartangle.com/tasks/task_abc123/complete" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"completionNotes": "Reviewed and sent feedback to Sarah"
}'
For recurring tasks, completing a task automatically creates the next occurrence.
Update a task
Update task properties. Only provided fields will be modified.
Update task · bash
curl -X PATCH "https://api.cleartangle.com/tasks/task_abc123" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dueDate": "2024-01-22T17:00:00Z",
"priority": "medium"
}'
Delete a task
Permanently delete a task.
Delete task · bash
curl -X DELETE "https://api.cleartangle.com/tasks/task_abc123" \
-H "Authorization: Bearer YOUR_API_KEY"
For recurring tasks, deleting removes only the single instance. Use ?deleteAll=true to delete the entire series.
Convenience endpoints
Get today’s tasks
GET /tasks/todayReturns all tasks due today, sorted by priority.Get overdue tasks
GET /tasks/overdueReturns all incomplete tasks past their due date.