All endpoints under /api/v1/. Authenticate with session cookie or API key Bearer token.
Authentication
Pass an API key as a Bearer token in the Authorization header:
Authorization: Bearer mt_your_api_key_here
Create API keys in the app under Account → API Keys.
Views
Read-only endpoints that return task lists for each GTD view.
| Endpoint | Description |
|---|
GET /inbox | Unprocessed inbox items |
GET /today | Tasks flagged for today + due today |
GET /in-progress | Tasks currently in progress |
GET /next | Next actions |
GET /waiting | Waiting/delegated tasks |
GET /someday | Someday/maybe list |
GET /upcoming | Scheduled + tasks with future due dates |
GET /logbook?limit=50 | Completed tasks (most recent first) |
GET /trash | Trashed items |
Tasks
| Endpoint | Description |
|---|
POST /tasks | Create a task. Body: { title, status?, projectId?, ... } |
GET /tasks/:id | Get a single task with full details |
PATCH /tasks/:id | Update any fields on a task |
POST /tasks/:id/complete | Mark task complete |
POST /tasks/:id/reopen | Reopen a completed task |
DELETE /tasks/:id | Move to trash |
Task Fields
| Field | Type | Notes |
|---|
title | string | Required on create |
notes | string | Free-text notes |
status | enum | inbox, next, waiting, scheduled, someday |
projectId | string? | UUID of parent project |
areaId | string? | UUID of area |
today | boolean | Flag for today’s focus |
inProgress | boolean | Currently being worked on |
energy | enum? | low, medium, high |
priority | number | 0 = none, 1-3 = !/!!/!!! |
sortOrder | number | Lower values appear first |
dueDate | string? | ISO date (YYYY-MM-DD) |
deferDate | string? | Don’t show until this date |
Projects
| Endpoint | Description |
|---|
GET /projects | All active projects |
GET /projects/:id | Project with all its tasks |
POST /projects | Create a project. Body: { title, areaId?, status? } |
Areas
| Endpoint | Description |
|---|
GET /areas | All areas |
GET /areas/:id | Area details |
POST /areas | Create area. Body: { name, notes? } |
PATCH /areas/:id | Update area |
DELETE /areas/:id | Delete area |
Search
| Endpoint | Description |
|---|
GET /search?q=&status=&energy=&projectId=&areaId= | Search tasks (case-insensitive). All params optional. |
Activity and Reviews
| Endpoint | Description |
|---|
GET /activity?limit=50 | Recent activity log |
GET /activity/agent?limit=50 | Agent-only activity |
GET /reviews/stats | Dashboard stats + throughput + project activity |
POST /reviews/start | Start a review. Body: { type: "weekly" | "daily" } |
API Keys
| Endpoint | Description |
|---|
GET /api-keys | List your API keys |
POST /api-keys | Create key. Body: { name }. Returns the key once. |
DELETE /api-keys/:id | Revoke a key |
Server-Sent Events
Subscribe to real-time task changes:
const es = new EventSource('/api/v1/events');
es.addEventListener('task-change', (e) => {
const { actor, action, taskId } = JSON.parse(e.data);
console.log(actor, action, taskId);
});