A REST API for your tasks and goals
Plain HTTPS and JSON, so it works from any language, any no-code tool that can make a request, and any agent that can run curl. Four endpoints cover your whole task tree, and responses leave out every field that isn't set.
What is the PerspecTask API?
The PerspecTask API lives at https://api.perspectask.com/v1 and authenticates with an API key sent as a Bearer token. GET /tasks lists your open tasks (flat or as a tree), GET /tasks/{id} reads one task with its subtree, POST /tasks creates a task or subtask, and PATCH /tasks/{id} changes status, priority, deadline, parents or text. The OpenAPI spec is public at /v1/openapi.yaml, and the SDK, CLI and MCP server are all generated from it or built on it.
# Open tasks under goal a3f, as a nested tree
curl "https://api.perspectask.com/v1/tasks/a3f?tree=true" \
-H "Authorization: Bearer pt_live_..."
# Create a subtask due next week
curl -X POST https://api.perspectask.com/v1/tasks \
-H "Authorization: Bearer pt_live_..." \
-H "Content-Type: application/json" \
-d '{"title": "Book venue", "deadline": "next week", "parent_id": "a3f"}'Ids can be the short prefix from any response or a full UUID. The full reference, generated from the spec, is in the API docs.
What makes it agent-friendly
Lean responses
No nulls and no empty arrays: worked_time appears only once a timer has run, completion only when a task has children. Done tasks are hidden unless you ask with showCompleted=true.
Short ids, one-token dates
Ids are shortened to their minimum unique prefix, like git hashes. Deadlines take today, next week, q3 or y2027 and come back as a canonical period id plus the exact end-of-period timestamp.
Scoped keys
tasks:read, tasks:write, and tasks:write:meta, which can change status, priority, deadline and parents but never the title or description of an existing task.
Frequently asked questions
- Is there a REST API for a task manager with goals?
- Yes. The PerspecTask API exposes your tasks as a tree: a task can have subtasks and several parent goals, each with a deadline period from a day to a lifetime. You can list, read, create and update them over HTTPS with an API key.
- How do I authenticate with the PerspecTask API?
- Create an API key in the web app under Account, API Keys, choosing only the scopes you need. Send it on every request as an Authorization: Bearer pt_live_... header. Keys can be revoked from the same page at any time.
- What errors does the API return?
- Errors come back as JSON with a status code: 400 for invalid input or an ambiguous short id (add a character), 401 for a missing or invalid key, 402 when an action needs the Pro plan, 403 for a missing scope or an encrypted task, and 404 when a task does not exist.
- Can the API read end-to-end encrypted tasks?
- No. PerspecTask is zero-knowledge: encrypted tasks are decrypted only in the app with your password, so the server only stores ciphertext and the API cannot read or modify them. They can be listed with includeEncrypted=true as placeholders with encrypted set to true and no title or description.
- Is there an OpenAPI spec?
- Yes, publicly at https://api.perspectask.com/v1/openapi.yaml. It is generated from the same schemas the server validates requests with, so it cannot drift from the real behavior, and you can generate a client in any language from it.
Call your goals from anywhere
Create a free scoped key and send your first request. Prefer typed code, a shell or MCP? The SDK, the CLI and the MCP server sit on the same API.