How to Connect an AI Agent to a Planner API

A planner API is not a calendar event API

Before writing integration code, define the data your agent actually needs. A planner API works with tasks, groups, settings, profile context, and planning analysis. It does not automatically mean Google Calendar or Outlook event sync, attendee management, availability search, or meeting booking.

That distinction prevents a common architecture mistake: choosing an API because its name sounds broad, then discovering that the data model does not match the workflow. Use the WeeklyPlanner Planner API when the agent should work with weekly planning data and you want explicit control over each HTTP request.

Decide whether you need direct API access

Direct REST access is a good fit when you are building:

• a server-side agent with its own tool-execution loop;
• a trusted automation that converts selected input into planner tasks;
• a review or reporting job that reads task state on a schedule;
• an internal service with explicit logging, retries, and error handling;
• an integration test around a fixed sequence of planner operations.

If a compatible AI client only needs ready-made planner tools, MCP may be the shorter path. If the user simply wants help inside WeeklyPlanner, the built-in AI Planner avoids external credentials entirely.

Design the agent loop before choosing endpoints

A safe integration separates language-model reasoning from authorized writes:

1. Receive a bounded user request. Define the dates, task group, or operation in scope.
2. Read planner context. Fetch only the data required for that request.
3. Generate a proposal. Let the model suggest changes without granting it raw credential access.
4. Validate with application policy. Check scopes, limits, IDs, allowed fields, and whether human approval is required.
5. Execute minimal writes. Send only the approved API calls from trusted server code.
6. Read back the result. Confirm that the planner now matches the intended change.

The model should not hold the API key or send arbitrary requests directly from generated text. Your application owns the credential and translates approved decisions into constrained calls.

Create one key for one integration

Create the key in Settings and give it only the scopes the workflow needs. Common scopes include:

• tasks:read for listing and inspecting tasks;
• tasks:write for creating or changing tasks;
• groups:read and groups:write for task-group workflows;
• stats:read for summary data;
• settings or profile scopes only when those resources are part of the use case.

A reporting agent usually does not need write access. A task-capture automation may need tasks:write but not profile or settings access. Separate keys prevent one integration from inheriting another integration's permissions and let you revoke access without rebuilding every connection.

Make the first request read-only

Keep the API key in a server-side environment variable. Then request a narrow task range from the configured site URL:

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

Do not put the key in browser JavaScript, a mobile bundle, a public repository, or the model prompt. If the agent runs in a desktop environment, place the secret in the host's protected configuration and keep tool execution outside generated content.

Verify authentication and response shape with this read before adding any mutation. A narrow date range also reduces unnecessary data exposure and request volume.

Add writes as explicit tools

Do not give the model a generic "call any URL" function. Define small application tools such as:

• read_week(date_from, date_to);
• create_planner_task(title, date, time_block);
• move_planner_task(task_id, date, time_block);
• complete_planner_task(task_id).

Each tool should validate its own inputs and map to a known endpoint. This makes agent traces readable and prevents a harmless planning prompt from turning into an unrestricted API client.

For high-impact operations, add a proposal object before execution. Store the requested changes, show them to the user, and call the API only after approval. After a batch, re-fetch the affected tasks rather than treating the model's narration as proof of success.

Handle quotas without hardcoding them into the agent

REST API and MCP calls share the account's external request pool. Current included allowances are sourced from the product facts used across the site:

• Free: 100 included external API/MCP requests in its current quota window.
• Pro and Lifetime: 1,000 included external API/MCP requests in their current quota window.

Treat these values as operational limits, not throughput targets. Cache stable reads where appropriate, avoid polling the same week repeatedly, and batch work only when the endpoint supports it. The authoritative current limits and plan comparison remain on the pricing page.

Build error handling into the workflow

The agent should not receive every failure as unstructured prose. Map API responses to a small set of decisions:

• 400: fix invalid input before retrying.
• 401: stop and replace or repair the credential through a secure operator flow.
• 403: request the missing scope or choose a read-only alternative.
• 404: re-read the resource list; the task may have moved or been removed.
• 429: respect Retry-After when present and wait instead of entering a tight loop.
• 503 rate_limit_unavailable: fail closed and retry later rather than bypassing the limiter.

Never replay a write blindly after a timeout. Read the affected resource first, determine whether the write already succeeded, and then decide whether another call is necessary.

Example: turn an approved message into a planner task

Consider an agent that receives a selected message and offers to add it to the week:

1. Extract a proposed title, date, time block, and optional notes.
2. Show the proposal without writing.
3. Ask the user to confirm or edit the fields.
4. Validate that the date and time block are allowed.
5. Create one task with a server-side call.
6. Read the created task and return its confirmed planner state.

The agent can help translate unstructured language into planner fields, but your code controls the permission boundary and final API call. This division is easier to test than letting a model improvise requests.

A production-readiness checklist

Before relying on the integration, verify that:

• the key is stored outside source code and prompts;
• scopes match the actual endpoints used;
• reads are limited to the required date and resource range;
• writes have input validation and an approval rule;
• logs redact authorization headers and sensitive content;
• 429 and temporary failures use bounded backoff;
• writes are followed by a read-back check;
• the key can be revoked without affecting other integrations.

Choose the connection, then keep one source of truth

The REST API is the right layer when you need custom orchestration and explicit control. MCP is better when a compatible assistant should discover a published set of planner tools. The Connect overview explains the three available paths, while AI planner versus calendar versus task manager helps decide where planning data should live.

Whatever execution layer you choose, do not create a separate task database just for the agent. Read from the planner, apply reviewed changes through the planner, and verify the result there. The full endpoint, scope, quota, and error reference lives on the authoritative WeeklyPlanner Planner API guide.