Quick Start

Get started with the PerspecTask API. Generate an API key, authenticate, and create your first task.

The PerspecTask API is a public REST API for managing your tasks programmatically. It operates on plaintext tasks — end-to-end-encrypted tasks appear in listings (so the tree structure stays intact) but their content is omitted.

Find the base URL

https://api.perspectask.com/v1

Authenticate

Every request is authenticated with an API key passed as a Bearer token. Keys start with pt_live_.

curl https://api.perspectask.com/v1/tasks \
  -H "Authorization: Bearer pt_live_..."

Scopes

Each key carries scopes that control what it can do:

tasks:read — read tasks (GET).
tasks:write — full create/update access.
tasks:write:meta — create/update everything except editing the title/description of existing tasks. Useful for automation that manages workflow (status, priority, scheduling, parents) without rewriting human-authored content.

Create your first task

curl -X POST https://api.perspectask.com/v1/tasks \
  -H "Authorization: Bearer pt_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "title": "Buy milk", "deadline": "today" }'

Key concepts

A Task has a title, optional description, a status, a priority, and an optional deadline. Tasks form a tree — a task can have multiple parents and children.
Deadlines use a single shorthand grammar. Write today, tomorrow, next week, lifetime, the bare letters d/w/m/q/y/l, or a column id like q-2-2026. On read, the API returns deadline as the canonical column id plus deadline_date (the actual end-of-period timestamp).
Completion is computed recursively from a task's descendants and is only present when the task has children.
Short ids. Task ids in responses are shortened to their minimum unique prefix (like a git commit hash) — often just 3 characters. Use the short prefix anywhere an id is accepted; the API resolves it and returns 400 if it's ambiguous.
Minimal payloads. Responses only include fields that are actually set — worked_time, completion, and created are omitted when empty or not requested. In tree mode a task with multiple parents is expanded once and referenced by id elsewhere, so shared subtrees aren't re-sent. This keeps payloads small and token-cheap for LLMs and agents.

Next steps

Building an integration or agent? See PerspecTask for AI Agents for the API, SDK, and CLI.
Browse the full API Reference for every endpoint with request/response schemas.