Connect your work.
REST API and MCP connect an agent you choose to your trees. Start with a read token; grant write permissions when you need them.
Getting started
Create a personal token in agent settings. Its value is shown once; choose its permissions and lifetime, and revoke access at any time.
OpenAPI 3.1 specification · Agent instructions
Token permissions
- read — read trees, tasks and notes, search, and export.
- write — create, change and delete data. Seed includes read-only API access; writes require Sprout or Grove.
- attachments — read attachment content in addition to read. Uploads also need write. Signed links expire within5 minutes.
REST API
Send the token in the Authorization header. The limit is 600 requests per minute per token; honor Retry-After when receiving 429.
curl https://taskwood.dzenity.com/api/v1/trees \
-H "Authorization: Bearer YOUR_TOKEN"
GET /api/v1/trees/{id}/export
GET /api/v1/tasks?updated_since=2026-10-07T00%3A00%3A00Z
GET /api/v1/search?q=Taskwood
POST /api/v1/tasks
PATCH /api/v1/tasks/{id}Lists return items and next_cursor, with 100 records by default and a maximum of 200. Keep the filters and limit unchanged and add cursor to subsequent requests until next_cursor is null.
GET /trees/{id}/export returns the entire tree with its projects and tasks. Lists use stable creation order; edits and deletions during traversal do not form an immutable snapshot.
The updated_since filter accepts ISO 8601 with a time zone and includes the boundary time. Deletes have no tombstone response; refresh the full snapshot to reconcile deleted records.
Reads include a private ETag. Send If-None-Match to receive 304 when unchanged. API data stays out of public caches.
Send a unique Idempotency-Key for a repeatable write. Keep it for a network retry with the same method, address and body; reusing it with a different body returns 409. Responses are retained for 7 days. Token creation does not support this header.
MCP
The /mcp endpoint uses Streamable HTTP with JSON responses. The client sends the same Bearer token, initializes, and retains the returned Mcp-Session-Id. A normal MCP client handles this automatically.
https://taskwood.dzenity.com/mcp
Authorization: Bearer YOUR_TOKENAvailable tools: list_trees, list_tasks, get_task, search, create_task, complete_task, get_attachment, transcribe_audio. Write tools appear only with the required permissions and plan. The taskwood://tree/{id} resource contains a full tree snapshot.
Upload files with POST /tasks/{id}/attachments (multipart, up to25 MiB). Read content at GET /attachments/{id}/content. Photos have GPS and camera metadata removed. Check GET /speech/status before transcription: an unconfigured provider returns503 and creates no job. Webhooks are being prepared.
Client connections
Cursor and Claude Code support a Bearer header. See agent settings for instructions. OAuth is being prepared for direct ChatGPT and Claude Desktop connections.