API Reference

All endpoints are rooted at the Schedule-X Cloud API base URL.

https://cloud.schedule-x.com

Authentication Headers

Organization API token for server-side organization routes:

X-ScheduleX-Api-Key: sx_org_...

Legacy organization API token header for low-level frontend-token exchange:

X-ScheduleX-Org-Token: sx_org_...

X-ScheduleX-Api-Key is also accepted by both frontend session/token endpoints and is preferred for new server integrations.

Frontend token for browser routes:

Authorization: Bearer sx_front_...

Users

Use the organization API token on your backend.

GET  /v1/orgs/{organizationId}/users
POST /v1/orgs/{organizationId}/users
GET  /v1/orgs/{organizationId}/memberships

Create user request:

{
  "email": "ada@example.com",
  "displayName": "Ada Lovelace",
  "role": "Member"
}

role can be Owner, Admin, Member, or Viewer.

Calendars

Use the organization API token on your backend.

GET  /v1/orgs/{organizationId}/calendars
POST /v1/orgs/{organizationId}/calendars

Create calendar request:

{
  "name": "Work",
  "slug": "work",
  "colorName": "work",
  "lightMainColor": "#2563eb",
  "lightContainerColor": "#dbeafe",
  "lightOnContainerColor": "#172554"
}

Required fields are name, slug, and colorName.

Calendar response:

{
  "id": "...",
  "organizationId": "...",
  "createdByUserId": "...",
  "name": "Work",
  "slug": "work",
  "colorName": "work",
  "lightMainColor": "#2563eb",
  "lightContainerColor": "#dbeafe",
  "lightOnContainerColor": "#172554",
  "darkMainColor": null,
  "darkContainerColor": null,
  "darkOnContainerColor": null,
  "permissionMode": "InternalOnly",
  "createdAt": "2026-06-03T10:00:00Z",
  "updatedAt": "2026-06-03T10:00:00Z",
  "deletedAt": null
}

Frontend Session Bootstrap

The recommended backend endpoint idempotently maps an authenticated application user and issues a one-hour frontend token.

POST /v1/orgs/{organizationId}/auth/frontend-session
X-ScheduleX-Api-Key: sx_org_...
Content-Type: application/json

{
  "externalUserId": "app-user-123",
  "email": "ada@example.com",
  "displayName": "Ada Lovelace"
}

The response has the frontend-token shape shown below. (organizationId, externalUserId) is unique; repeated calls update profile fields, preserve the membership role, and issue a fresh token.

Low-Level Frontend Token Exchange

Use this endpoint when your backend manages Cloud user IDs itself.

POST /v1/orgs/{organizationId}/auth/frontend-token
X-ScheduleX-Org-Token: sx_org_...
Content-Type: application/json

Request:

{
  "userId": "..."
}

Response:

{
  "token": "sx_front_...",
  "organizationId": "...",
  "userId": "...",
  "expiresAt": "2026-05-28T12:00:00Z"
}

Browser

Browser routes use a frontend token:

Authorization: Bearer sx_front_...

Load Schedule-X config:

GET /v1/schedule-x/config

Optional filters:

GET /v1/schedule-x/config?from=2026-05-01T00:00:00%2B00:00&to=2026-06-01T00:00:00%2B00:00&calendarIds=work,personal

Persist events:

POST   /v1/events
PATCH  /v1/events/{eventId}
DELETE /v1/events/{eventId}

Create event request:

{
  "calendarId": "...",
  "title": "Planning",
  "description": "Weekly planning session",
  "location": "Room 12",
  "start": "2026-06-10T09:00:00+02:00",
  "end": "2026-06-10T10:00:00+02:00",
  "timeZone": "Europe/Berlin",
  "isAllDay": false,
  "isPrivate": false,
  "recurrenceRule": null,
  "recurrenceExDates": [],
  "people": ["ada@example.com"]
}

Required fields are calendarId, start, end, and timeZone. start and end accept Schedule-X date-time strings with an offset. timeZone must be a valid IANA or system time zone id.

Backend config endpoint (organization API token only):

GET /v1/orgs/{organizationId}/schedule-x/config

Frontend tokens cannot use this endpoint. Browser code must use GET /v1/schedule-x/config, which derives the organization, environment, and user from the frontend token.

Google Calendar Sync

Google Calendar routes use a frontend token:

Authorization: Bearer sx_front_...

GET    /v1/integrations/google-calendar/connect-url
GET    /v1/integrations/google-calendar/connections
DELETE /v1/integrations/google-calendar/connections/{connectionId}
GET    /v1/integrations/google-calendar/provider-calendars
POST   /v1/integrations/google-calendar/provider-calendars/sync
GET    /v1/integrations/google-calendar/connections/{connectionId}/provider-calendars
POST   /v1/integrations/google-calendar/connections/{connectionId}/provider-calendars/{providerCalendarId}/sync
GET    /v1/integrations/google-calendar/sync-status

Create a Google OAuth URL:

GET /v1/integrations/google-calendar/connect-url?returnUrl=https://app.example.com/calendar

The returnUrl origin must be registered for the frontend token’s environment in the Cloud console. It is validated before OAuth state is created. Omitting returnUrl leaves the callback response on the Schedule-X Cloud API.

Sync one provider calendar:

{
  "name": "Work"
}

The organization must have the GoogleCalendarSync entitlement.

Server Event Routes

Backend code can also list and create events with an organization token:

GET  /v1/orgs/{organizationId}/events
POST /v1/orgs/{organizationId}/events

The browser routes are preferred for user-initiated calendar editing because they preserve the frontend-token user as the event writer.

Subscriptions And Entitlements

GET /v1/orgs/{organizationId}/subscription
GET /v1/orgs/{organizationId}/entitlements

These endpoints return the organization subscription and enabled feature limits for the current plan.

Errors

Error responses use a JSON error envelope:

{
  "error": {
    "code": "invalid_event_time_range",
    "message": "Event end must be after event start."
  }
}

Common statuses:

Status	Meaning
400	Request body or query parameters are invalid
401	Missing or invalid credentials
403	The authenticated user cannot perform the action
404	The organization, calendar, user, or event was not found
409	A unique value, such as a slug or email, already exists
429	Rate limit exceeded