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" } }
StatusMeaning
400Invalid input; the message says what.
401Missing or invalid API key.
402The free plan's task limit is reached.
404The task doesn't exist or isn't yours.
409A request with the same Idempotency-Key is still being processed. Try again in a moment.
422This Idempotency-Key was already used for a different request.
429More 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"}'

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 &lt; 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, …] }.

QueryValues
statusopen, completed or all (default)
sortcreated (default) or completed (most recently completed first)
searchOnly tasks whose title contains this text
limit1–100, default 25

GET /tasks/{id}

One task.

POST /tasks

Creates a task and answers 201 with it. Only title is required.

FieldDescription
titleUp to 255 characters
notesPlain 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.
dateYYYY-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.
deadlineYYYY-MM-DD, or an ISO date-time
estimate_minutesWhole minutes
prioritynone, low, medium, high or urgent
project_id, tag_idFrom /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.