Planner API

Connect Automations to a Plan People Actually Use

Give an AI agent, script, or workflow structured access to the same tasks, groups, settings, and planning data already living in WeeklyPlanner.

Create an accountUse the MCP server
JSON REST endpointsRevocable scoped keysShared planner data

A real plan, not a mock integration

Your assistant works through a scoped connection

Create a revocable key in WeeklyPlanner, connect a compatible agent, and let the workflow read or update the same plan you can inspect in the app.

  1. Your request
  2. Task Planner Skill
  3. Scoped MCP or API
  4. WeeklyPlanner plan
WeeklyPlanner mobile settings showing the connection area
Real settings UIScoped permissionsRevocable key

What you can automate

The API is useful when a workflow needs to read or change a real plan, not merely export another copy of a to-do list.

Build a reliable weekly brief

Pull tasks, dates, time blocks, priorities, tags, notes, and completion state into a dashboard, report, or agent context.

Capture work from other systems

Turn approved form submissions, messages, or workflow events into planner tasks with a date, group, priority, and time block.

Rebalance work when plans change

Move selected tasks across dates or time blocks, update fields in batches, and preserve one shared source of truth.

Review what actually happened

Read planning statistics alongside completed and deferred tasks to create weekly reviews grounded in account data.

Connect to planner capabilities

These are task-planning operations, not calendar-provider event sync. Every request works against the authenticated account's planner data.

Tasks and recurring series

List, filter, create, inspect, update, delete, reorder, and batch-change tasks, with dedicated recurring-series operations.

Groups

Read and maintain the names, colors, and ordering used to organize tasks across the planner.

Settings and profile

Read or update planning preferences, locale, view settings, and selected personal planning context.

Statistics and subscription context

Read aggregate task statistics and the current subscription context for dashboards or agent decisions.

Security and permission boundaries

Start with one API key per connection and grant only the operations that workflow needs.

Bearer API keys

Create a key in Settings, save the plaintext value when it is shown, and send it in the Authorization header. Never put it in client-side code or prompts.

Separate read and write scopes

A reporting workflow can stay read-only. Add write scopes only for integrations that must create, move, edit, or delete planner data.

Revoke each connection independently

Use a separate key for every agent, script, or automation so one retired workflow can be revoked without interrupting the others.

Validate and rate-limit every request

The API authenticates the caller, checks required scopes, validates inputs, and applies the account's external API/MCP request limit.

Available API scopes

Scopes are sourced from the same application constants used when keys are created in Settings.

tasks:readtasks:writegroups:readgroups:writestats:readsettings:readsettings:writeprofile:readprofile:write

External request allowances

REST API and MCP calls share the external request pool. Built-in AI turns are measured separately.

  • Free includes 100 external API/MCP requests per rolling 24 hours
  • Pro and Lifetime include 1,000 external API/MCP requests per hour

You may not need to write API code

Choose the lightest connection that proves the workflow is valuable before maintaining a custom integration.

Use the built-in AI planner

Ask for summaries and scheduling changes in natural language without creating or storing an external API key.

Explore the AI planner

Configure the MCP server

Connect Claude or another stdio-compatible client with a published package and scoped key instead of writing REST calls.

Open the MCP guide

Work directly in the planner

For a personal workflow with no repeated integration need, the visual weekly planner is simpler and cheaper to maintain.

Open the planner

REST API quickstart

Use a server-side environment or secret manager. The examples call the public v1 API directly with a scoped key.

Create a key in Settings

  1. 1. Create a scoped key

    Open Settings, create one key for this integration, and select the smallest read or write scope set.

  2. 2. Store it outside source control

    Save the plaintext key immediately in the automation's server-side secret store. It is not a browser-safe credential.

  3. 3. Make a read-only request first

    List a narrow date range, confirm the response shape, then add write scopes and mutation calls only when required.

List tasks for a week

Filter by an inclusive date range. The response uses a top-level data field.

curl "https://weeklyplanner.cc/api/v1/tasks?date_from=2026-08-03&date_to=2026-08-09" \
  -H "Authorization: Bearer wp_your_api_key" \
  -H "Content-Type: application/json"

Create a planner task

A write call requires tasks:write and is subject to the account's normal product limits.

curl -X POST "https://weeklyplanner.cc/api/v1/tasks" \
  -H "Authorization: Bearer wp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Prepare weekly review",
    "date": "2026-08-07",
    "time_block": "evening",
    "priority": "high"
  }'

Core endpoint reference

The list below focuses on stable planning endpoints. Route-specific validation can return more precise 4xx codes than the common responses shown later.

Tasks and recurring series

Read and mutate individual tasks, apply batch updates, persist ordering, and manage a recurring series explicitly.

GET /api/v1/tasksPOST /api/v1/tasksGET|PATCH|DELETE /api/v1/tasks/:idPOST /api/v1/tasks/batchPOST /api/v1/tasks/reorderGET|PATCH|DELETE /api/v1/series/:id

Groups

List and create groups, then inspect, edit, or delete one group.

GET|POST /api/v1/groupsGET|PATCH|DELETE /api/v1/groups/:id

Settings and profile

Read or update planner preferences and selected profile context.

GET|PATCH /api/v1/settingsGET|PATCH /api/v1/user/profile

Statistics and subscription

Read aggregate task statistics and the current subscription status.

GET /api/v1/statsGET /api/v1/subscription/status

Common responses and error codes

Successful resource responses use a top-level data field. Errors include a machine-readable code and human-readable error message.

400validation_failed

The query or JSON body failed schema or domain validation; inspect the optional details field.

401unauthorized

The Bearer credential is missing, invalid, expired, or no longer active.

403missing_scope

The key is valid but does not include the scope required by this operation.

404not_found

The requested account resource does not exist or is not visible to this caller.

429rate_limit_exceeded

The external request allowance is exhausted. Respect Retry-After when present instead of retrying in a tight loop.

503rate_limit_unavailable

The atomic rate-limit reservation is temporarily unavailable, so the API fails closed and asks the client to retry later.

500internal_error

An unexpected server error occurred. Do not expose or log the API key while collecting diagnostics.

Explore related pages

ConnectMCP Task ManagerAI Agent API GuideAI Weekly PlannerPlans and API Limits

Planner API FAQ

Is this a calendar API?
No. It is a planner and task API for the tasks, groups, settings, profile context, and statistics stored in WeeklyPlanner. It does not claim to be a calendar-provider event or availability API.
Do I need to code to connect an AI assistant?
Not necessarily. The built-in AI planner requires no external key, and the MCP package gives compatible assistants structured tools with configuration instead of custom REST code.
Can an API key change my plan?
Only when it has the relevant write scope. Use read-only scopes for summaries and reporting, and create a separate key for every connection.
Do REST API and MCP requests have separate quotas?
No. They share the same external API/MCP request pool for the account. Built-in AI turns are a separate allowance.