Planzer.io API
Read and create tasks and get notified when tasks are created or completed. It powers the Planzer.io apps for Zapier and Make, and you can use it from your own scripts.
Base URL: https://api.planzer.io/v1 · OpenAPI: openapi.json · Help: [email protected]
Authentication
Create a personal API key in Planzer under Settings → Integrations → API keys. It's shown once; copy it right away. Send it with every request:
curl https://api.planzer.io/v1/me \
-H "Authorization: Bearer pk_your_key"
A key gives full access to the tasks of the account that created it. Delete a key in the same place to revoke it; Zaps, scenarios and webhooks using it stop right away.
Errors and limits
Errors use HTTP status codes with a JSON body:
{ "error": { "status": 400, "message": "title is required" } }
| Status | Meaning |
|---|---|
| 400 | Invalid input; the message says what. |
| 401 | Missing or invalid API key. |
| 402 | The free plan's task limit is reached. |
| 404 | The task doesn't exist or isn't yours. |
| 409 | A request with the same Idempotency-Key is still being processed. Try again in a moment. |
| 422 | This Idempotency-Key was already used for a different request. |
| 429 | More than 120 requests per minute for one API key (or one IP address without a valid key). Wait the number of seconds in the Retry-After header. |
Safe retries (Idempotency-Key)
A POST that timed out may still have worked. To retry it without creating the task (or webhook) twice, send an Idempotency-Key header with a value that's unique to that one request, such as a UUID, and send the same key again on each retry:
curl https://api.planzer.io/v1/tasks \
-H "Authorization: Bearer pk_your_key" \
-H "Idempotency-Key: 6f1c2a7e-3b9d-4e57-9c31-0d8a4f2b9e10" \
-H "Content-Type: application/json" \
-d '{"title":"Send the invoice"}'
- Works on
POST /v1/tasks,POST /v1/tasks/{id}/completeandPOST /v1/webhooks. - For 24 hours, a repeat of the same request with the same key gets the first answer back, with the header
Idempotent-Replayed: true. Nothing is done twice. - The same key with a different body or endpoint answers
422. While the first request is still running, a repeat answers409. - Answers with a 5xx status aren't kept, so retrying after a server error runs the request again.
- Keys belong to your API key, and can be up to 255 printable characters without spaces. Without the header, requests work as before.
The task object
{
"id": "6f1c2b8e-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
"title": "Send the proposal to Acme",
"notes": "Attach the pricing sheet.",
"status": "open", // open | completed
"date": "2026-10-06", // planned day; null = inbox
"deadline": "2026-10-10",
"estimate_minutes": 45,
"priority": "high", // none | low | medium | high | urgent
"project": { "id": "…", "name": "Acme" },
"tag": { "id": "…", "name": "Work" },
"source": "PLANZER", // or the integration it came from
"created_at": "2026-10-06T08:00:00.000Z",
"completed_at": null,
"url": "https://app.planzer.io/dashboard"
}
notes is HTML, the same as the task description in the app: a note sent as a < b plus a line break comes back as a < b<br />. Sending notes you read from the API back in (for example when copying a task) stores them unchanged. title is plain text.
Account
GET /me
The account the key belongs to: id, name, email, timezone. Useful to test a key.
Tasks
GET /tasks
Lists tasks, newest first, as { "data": [Task, …] }.
| Query | Values |
|---|---|
status | open, completed or all (default) |
sort | created (default) or completed (most recently completed first) |
search | Only tasks whose title contains this text |
limit | 1–100, default 25 |
GET /tasks/{id}
One task.
POST /tasks
Creates a task and answers 201 with it. Only title is required.
| Field | Description |
|---|---|
title | Up to 255 characters |
notes | Plain text or HTML. Plain text is kept as written (line breaks too). HTML is limited to basic formatting and http, https and mailto links; anything else, like scripts, is removed. |
date | YYYY-MM-DD, today, or an ISO date-time (read as the day it is in the account's time zone). Leave out to add it to the inbox. |
deadline | YYYY-MM-DD, or an ISO date-time |
estimate_minutes | Whole minutes |
priority | none, low, medium, high or urgent |
project_id, tag_id | From /projects and /tags. An id that isn't there answers 400 and no task is created. |
curl -X POST https://api.planzer.io/v1/tasks \
-H "Authorization: Bearer pk_your_key" \
-H "Content-Type: application/json" \
-d '{ "title": "Call Anna", "date": "today", "estimate_minutes": 15 }'
POST /tasks/{id}/complete
Completes the task like ticking it off in the app (a running timer on it is stopped) and answers with the task. Completing a completed task changes nothing.
Projects and tags
GET /projects
Active projects: { "data": [{ "id", "name", "color", "due_date" }] }.
GET /tags
Tags: { "data": [{ "id", "name", "color" }] }.
Webhooks
Get notified the moment a task is created or completed, anywhere in Planzer (web, desktop, phone or an integration).
POST /webhooks
{ "event": "task.created", "target_url": "https://hooks.example.com/planzer" }
Events: task.created, task.completed. Answers 201 with { "id", "event", "target_url" }. The URL must be a public https address; up to 50 webhooks per account.
DELETE /webhooks/{id}
Unsubscribes. Answers 204, also when the webhook is already gone.
What you receive
POST https://hooks.example.com/planzer
Content-Type: application/json
{ "event": "task.completed", "created_at": "2026-10-06T15:30:00.000Z", "data": { …task… } }
Answer with any 2xx status. Answer 410 Gone to unsubscribe. Deliveries time out after 10 seconds and aren't retried. Deleting the API key removes the webhooks it created.
MCP server for AI assistants
Claude, ChatGPT, Codex, Cursor and other assistants that speak the Model Context Protocol can read and plan the user's day: tasks, time blocks and calendar events. Part of Planzer Pro.
https://api.planzer.io/mcp
Add it as a custom connector (remote MCP server, Streamable HTTP). Assistants that support OAuth sign in to Planzer in the browser and get a key of their own, listed under Settings → Integrations → API keys. Others can send an API key instead:
Authorization: Bearer pk_your_key
Tools: get_day, list_tasks, list_inbox, search_tasks, get_task, create_task, update_task, complete_task, reopen_task, delete_task, schedule_task, unschedule_task, list_calendar_events, list_projects, list_tags, start_timer, stop_timer. Dates and times are in the user's time zone.
OAuth: discovery at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server, dynamic client registration, authorization code with PKCE (S256), public clients.