REST API

Day Planner’s REST API lets scripts, dashboards and AI agents read and change your planner over HTTPS. Every endpoint lives under /api on your instance, such as https://tasks.example.com/api/tasks, and speaks JSON.

For AI agents, the MCP server is the friendlier way to use this same API: tools such as create_task accept names instead of ids and collect paginated results for you.

Authentication

Every request acts as one user, so it needs either the session cookie from signing in to the web app or an API key belonging to your account. Send a key in either header:

curl -H "Authorization: Bearer dp_change-me" https://tasks.example.com/api/tasks
curl -H "x-api-key: dp_change-me" https://tasks.example.com/api/tasks

Both requests list your open tasks. See API keys to create a key, and How sign-in and API keys work for what a key can and can’t do. A missing, invalid or revoked key gets 401 Unauthorized:

{
  "error": "Unauthorized — provide a valid API key or sign in"
}

The message is the same whether the key is missing, wrong, revoked or rate-limited. Only the health endpoint works without sign-in. You can read and change only your own data: an id belonging to any other user returns 404 Not Found.

Requests and responses

Send request bodies as JSON with a Content-Type: application/json header. Timestamps are ISO 8601 in UTC. Responses are JSON too, in one of three shapes:

one object, for a single resource,
an array, for the list endpoints on projects, spaces and labels,
a data array plus a pagination object, for list tasks — the only paginated endpoint.

Delete endpoints answer {"success": true}. All ids are UUIDs.

Errors

Failed requests return a JSON object with an error message. A validation failure (400 Bad Request) adds details with the validator’s formErrors and fieldErrors, naming every field that failed. When a body names a record you don’t own, the response names that field:

{
  "error": "spaceId not found",
  "field": "spaceId"
}

Creating a task with a spaceId from another account produces that response. A 404 Not Found answer looks like {"error": "Task not found"}: the id either doesn’t exist or belongs to someone else.

A body that isn’t valid JSON gets 400 Bad Request with {"error": "Invalid JSON"}. While the instance still needs first-run setup, every endpoint except the health check answers 503 Service Unavailable with {"error": "Server configuration needed; see /config-needed"}.

Rate limits

Each API key allows 600 requests per minute, counted per key. The allowance resets after a minute without traffic on that key, so a steady caller won’t see it reset at a clock minute. Once a key passes its limit, requests signed with it stop authenticating and come back 401 Unauthorized; slow down, then retry. The body is identical to the one for a missing or revoked key, so nothing tells you the limit was the cause. Requests made with a session cookie don’t draw on any key’s allowance.

Pagination

Only list tasks is paginated. Its page parameter starts at 1, and limit defaults to 50 with a maximum of 100. The response reports page, limit, total and pages, so you can fetch one page after another:

curl -H "Authorization: Bearer dp_change-me" "https://tasks.example.com/api/tasks?page=1&limit=100"

The result’s pagination object tells you how many pages remain. The MCP server follows every page for you.

Resources

Resource	What it covers
Tasks	Work items, with filtering and bulk actions
Projects	Goals that group tasks and documents
Spaces	Top-level areas that hold projects, tasks and documents
Labels	Tags you can attach to tasks
Documents	Notes, specs and links
Checklist items	Sub-items within a task
Time blocks	Scheduled and manually placed slots in the calendar
Notifications	Morning summaries and deadline alerts
Planner	Re-planning auto-scheduled work
Schedule preferences	Named time windows the scheduler honours
User	Your profile