Skip to content

api.md

Latest commit

 

History

History
428 lines (310 loc) · 6.52 KB

api.md

File metadata and controls

428 lines (310 loc) · 6.52 KB
Raw
type reference
domain complicated
audience practitioner
stability structural
authority
provenance verifiability evidence currency
institutional
executable
moderate
undated
epistemic-layer practice

HTTP API Reference

Task exposes a REST API when running the server with task serve.

Starting the Server

task serve --port 3000

Options:

Option Default Description
--port 3000 Port to listen on
--hostname 127.0.0.1 Hostname to bind to

Task Endpoints

List Tasks

GET /tasks

Query parameters:

Parameter Type Description
q string Text search in title and description
status string Filter by status: todo, in-progress, done
priority number Filter by priority: 0 (Normal), 1 (High), 2 (Urgent)
project string Filter by project name
tag string Filter by tag name
overdue boolean Only overdue tasks
due_before string Tasks due before date (ISO 8601)
due_after string Tasks due after date (ISO 8601)
semantic string Semantic search query
all boolean Include completed tasks
limit number Maximum results (1-100)

Boolean flags (all, overdue) accept true or 1; any other value is treated as false. When limit is omitted, semantic search returns 10 results and normal listing is unlimited.

Create Task

POST /tasks

Body:

{
  "title": "Task title",
  "description": "Optional description",
  "due_date": "2025-12-31T10:00:00Z",
  "due_date_natural": "next friday",
  "project": "Project Name",
  "parent_id": 42,
  "tags": ["bug", "auth"],
  "recurrence": { "type": "weekly", "interval": 1, "daysOfWeek": [1] },
  "duration_hours": 1.5
}

Only title is required. project is created if it doesn't exist. recurrence is a structured rule object (the CLI parses natural language like "every Monday" into this shape); it is only allowed on top-level tasks. New tasks always start as todo with priority 0 — set status/priority with a follow-up PATCH.

Get Task

GET /tasks/:id

Update Task

PATCH /tasks/:id

Body (all fields optional):

{
  "title": "New title",
  "description": "New description",
  "status": "done",
  "priority": 2,
  "due_date": "2025-12-31T10:00:00Z",
  "project_id": 3,
  "order": 5,
  "recurrence": { "type": "daily", "interval": 1 },
  "duration_hours": 2
}

project_id, recurrence, and duration_hours accept null to clear the value. Setting status to done on a recurring task creates the next instance and returns its id as recurring_next_task_id.

Delete Task

DELETE /tasks/:id

Deletes the task and all its subtasks (cascade delete), along with their comments, attachments, and stored embeddings. Returns 404 if the task doesn't exist — as do all DELETE endpoints for missing resources.

Bulk Update

PATCH /tasks/bulk

Body:

{
  "ids": [1, 2, 3],
  "update": { "status": "done" }
}

Bulk Delete

DELETE /tasks/bulk

Body:

{
  "ids": [4, 5, 6]
}

Batch Create

POST /tasks/batch

Body:

{
  "tasks": [
    {
      "title": "Parent task",
      "subtasks": [
        { "title": "Subtask 1" },
        { "title": "Subtask 2" }
      ]
    }
  ]
}

Complete Subtasks

POST /tasks/:id/complete-subtasks

Comment Endpoints

List Comments

GET /tasks/:id/comments

Add Comment

POST /tasks/:id/comments

Body:

{
  "content": "Comment text"
}

Attachment Endpoints

List Attachments

GET /tasks/:id/attachments

Add Attachment

POST /tasks/:id/attachments

Multipart form data with file upload.

Tag Endpoints

List All Tags

GET /tags

Create Tag

POST /tags

Body:

{
  "name": "tag-name"
}

Rename Tag

PATCH /tags/:id

Body:

{
  "name": "new-name"
}

Delete Tag

DELETE /tags/:id

List Tags on Task

GET /tasks/:id/tags

Add Tags to Task

POST /tasks/:id/tags

Body:

{
  "tags": ["bug", "urgent"]
}

Replace Tags on Task

PUT /tasks/:id/tags

Same body as adding tags; replaces the task's full tag set.

Remove Tag from Task

DELETE /tasks/:id/tags/:tagId

Tags left unused by any task are removed automatically.

Project Endpoints

List Projects

GET /projects

Create Project

POST /projects

Body:

{
  "name": "Project Name"
}

Google Calendar Endpoints

Auth Status

GET /gcal/status

List Calendars

GET /gcal/calendars

Sync Task

POST /gcal/sync/:taskId

Body:

{
  "durationHours": 2,
  "calendarId": "primary",
  "dueDate": "2025-12-31T10:00:00Z"
}

All fields optional. durationHours must be 0.25-24. dueDate provides a start time for tasks without a due date. If the linked event was deleted in Google Calendar, a new event is created and the task re-linked.

Batch Sync

POST /gcal/sync/batch

Body:

{
  "taskIds": [1, 2, 3]
}

List Synced Tasks

GET /gcal/synced

List Unsynced Tasks

GET /gcal/unsynced

Other Endpoints

Health Check

GET /health

Statistics

GET /stats

Activity Reports

GET /reports

Query parameters:

Parameter Type Description
period string week, month, or quarter
from string Start date (ISO 8601)
to string End date (ISO 8601)
project string Filter by project

Parse Text to Tasks

POST /parse

Body:

{
  "content": "- Task 1\n- Task 2",
  "format": "markdown",
  "defaults": { "project": "Inbox", "priority": 1 }
}

format is text (default), markdown, or json. defaults is optional.