Skip to main content

​
Calendar

The content calendar is the project’s day-by-day view: scheduled and planned posts, note slots, idea placements, and the recurring posting-time template. The REST surface is read-only — two endpoints, both requiring the calendar:read scope — grantable to API keys and OAuth tokens alike (see auth.md §1.2). Scheduling itself is a posts write (PATCH /v1/posts/{postId} with scheduledFor), and the recurring template is writable via the MCP update_posting_schedule tool (calendar:write, two-phase). Read the current template from GET /v1/settings → calendar.schedule. Full schemas: OpenAPI reference → Calendar.

​
GET /v1/calendar

A project’s calendar for a date range.
  • from / to are inclusive calendar days (YYYY-MM-DD), max 92 days per request.
  • Days are interpreted in the project’s calendar timezone, not UTC — “what goes out on Tuesday” is a wall-clock question. The response echoes which timezone was used.
  • Each day carries its scheduled/planned posts (with workflow status category and any lastPublishError), note slots, idea placements, and whether the recurring posting-time template expects a post that day.
Never report a scheduled post as “on its way” from scheduledAt alone — read the post’s delivery verdict (due vs missed) on Posts.

​
GET /v1/calendar/next-free-slot

The next free posting slot for a project, computed from the recurring template exactly the way the dashboard computes it.
The response spells the slot out: iso (absolute UTC instant), timezone (always an IANA name — projects holding the legacy "CET" abbreviation are reported as the zone it is equivalent to), date / time (the project’s own wall clock), utcOffset, localTime (Sat, 15 Aug 2026 09:00 (Europe/Berlin) — the string to show a user), and source: template (a configured posting-time slot) or fallback (no usable template; 09:00 on the first open day as a suggestion — say so). Feed iso straight into a scheduling write; don’t convert it yourself. “Free” is checked against the whole calendar — posts, note slots, idea placements — so after scheduling into the returned slot, call again and you get the next one.

​
Agent access

The MCP tools list_calendar and get_next_free_slot are 1:1 twins of these endpoints — see MCP tools.