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

Method	Endpoint	Description
`GET`	`/tasks`	List all tasks
`POST`	`/tasks`	Create a task
`GET`	`/tasks/:id`	Get a task
`PATCH`	`/tasks/:id`	Update a task
`DELETE`	`/tasks/:id`	Delete a task
`POST`	`/tasks/:id/complete`	Mark task complete
`POST`	`/tasks/:id/uncomplete`	Mark task incomplete
`GET`	`/tasks/today`	Get tasks due today
`GET`	`/tasks/overdue`	Get overdue tasks

Task Object

A task object contains the following properties:

Field	Type	Description
`id`	string	Unique task identifier
`title`	string	Task title
`description`	string	Optional detailed description
`status`	string	pending, completed, or cancelled
`dueDate`	ISO8601	Due date and time
`priority`	string	low, medium, high, or urgent
`projectId`	string	Associated project ID
`tags`	string[]	Array of tags
`estimatedMinutes`	integer	Estimated time to complete
`sourceCapture`	string	ID of capture task was extracted from
`recurrence`	object	Recurrence configuration
`completedAt`	ISO8601	Completion timestamp

Create a Task

Create a new task with optional recurrence settings.

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

{
  "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.

curl -X GET "https://api.cleartangle.com/tasks?status=pending&priority=high&dueDate=2024-01-20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Parameter	Description
`status`	Filter by status (pending, completed, cancelled)
`priority`	Filter by priority (low, medium, high, urgent)
`projectId`	Filter by project
`tags`	Comma-separated tag filter
`dueDate`	Filter by due date (exact or range with startDate/endDate)
`overdue`	Set to true to only show overdue tasks
`sort`	Sort field (dueDate, priority, createdAt)
`order`	Sort order (asc, desc)

Complete a Task

Mark a task as completed with optional completion notes.

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.

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.

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/today

Returns all tasks due today, sorted by priority.

Get Overdue Tasks

GET /tasks/overdue

Returns all incomplete tasks past their due date.