> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.scripe.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Calendar

# 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](./auth.md#12-scopes)). Scheduling itself is a *posts*
write (`PATCH /v1/posts/{postId}` with `scheduledFor`), and the
recurring template is writable via the MCP
[`update_posting_schedule`](./mcp-tools.md#27-the-posting-schedule-update_posting_schedule)
tool (`calendar:write`, two-phase). Read the current template from
[`GET /v1/settings`](./settings.md) → `calendar.schedule`.

Full schemas: **OpenAPI reference → Calendar**.

***

## `GET /v1/calendar`

A project's calendar for a date range.

```bash theme={null}
curl -s "https://api.scripe.io/v1/calendar?projectId=proj_…&from=2026-08-17&to=2026-08-23" \
  -H "Authorization: Bearer scripe_oat_…" \
  -H "Scripe-Api-Version: 2026-08-10"
```

* `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](./posts.md).

## `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.

```bash theme={null}
curl -s "https://api.scripe.io/v1/calendar/next-free-slot?projectId=proj_…" \
  -H "Authorization: Bearer scripe_oat_…" \
  -H "Scripe-Api-Version: 2026-08-10"
```

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](./mcp-tools.md#1-read-tools).