Meet the new Scripe, live on October 7.Register

OpenAPI reference · Calendar

The next free posting slot for a project

GET/calendar/next-free-slot

The next free slot from the project's posting-time template (fallback: 09:00 on the first open day when no template is configured, or when nothing in the template is free). Same computation the dashboard and the chat's scheduling proposal use.

Free means no post is already scheduled at that exact minute and nothing else on the calendar reserves that day — so after you schedule something into the returned slot, calling this again returns the NEXT one. That is how several posts get spread out; before 2026-08 the no-template branch skipped the occupancy check entirely and answered the same instant every time.

Requires the calendar:read scope.

Authorization

  • Authorizationstringrequired

    Bearer token in the Authorization header.

    Pass Authorization: Bearer scripe_sk_live_<...> (or scripe_sk_test_<...> for test keys) on every request. Keys are scoped to a single workspace and can be revoked from the Scripe dashboard.

    The same header also accepts an OAuth 2.1 access token (scripe_oat_*); both credentials share one scope vocabulary and every operation below documents the scope it requires. An API key can hold every scope named on this surface except webhooks:manage, which is grantable to OAuth tokens only today — the webhook-endpoint operations answer 403 scope_missing to every API key. Operations that name no scope accept any valid token of the workspace.

Query parameters

  • projectIdstringrequired

Header parameters

  • Scripe-Api-Versionstring

    Pin the API version. Format YYYY-MM-DD. Omit to receive the currently rolling default. Unknown versions return 400 version_unsupported.

Responses

  • 200

    The suggested slot.

  • 400

    Malformed request (bad cursor, bad limit, etc.).

  • 401

    Missing, malformed, expired, or revoked API key.

  • 403

    Plan not eligible, scope missing, or workspace mismatch.

  • 404

    Resource not found in this workspace.

  • 429

    Sliding-window rate limit exceeded.

Example request

bash
curl --request GET \
  --url 'https://api.scripe.io/v1/calendar/next-free-slot?projectId=<projectId>' \
  --header 'Authorization: Bearer <token>'

Example response (200)

json
{
  "data": {
    "iso": "2026-08-12T07:00:00.000Z",
    "timezone": "Europe/Berlin",
    "date": "2026-08-12",
    "time": "09:00",
    "utcOffset": "+02:00",
    "localTime": "Wed, 12 Aug 2026 09:00 (Europe/Berlin)",
    "source": "template"
  }
}