Scheduling API vs calendar API

You want users to book a meeting in your app, so you reach for an API. Then the question lands: do you read and write calendar events yourself, or do you hand off the whole “find a free slot, confirm it, put it on everyone’s calendar” dance to something higher level? Pick wrong and you either rebuild a booking engine from scratch on top of raw event endpoints, or you fight a rigid booking widget when all you needed was to drop one event onto a calendar.

The two answers are a calendar API and a scheduling API. They sound interchangeable. They aren’t. This recipe draws the line between them, shows the real Nylas endpoints behind each, and gives you a clear rule for which one fits the integration you’re building.

What is the difference between a scheduling API and a calendar API?

A calendar API gives you raw CRUD over events and calendars: create, read, update, and delete entries directly. A scheduling API sits one layer up and runs the booking workflow for you, computing real-time availability across attendees and confirming the booking. With Nylas you read events through GET /v3/grants/{grant_id}/events and run booking flows through the /v3/scheduling/ endpoints.

Think of it as primitives versus a workflow. The calendar API is the building block: it tells you what’s on a calendar and lets you change it, and nothing more. The scheduling layer composes those primitives into the end-to-end “offer slots, capture a choice, write the event” sequence that appointment apps need. A Free/Busy lookup runs in well under 1 second, but a booking flow is many calls. The table below maps each job to the right surface.

Job	Calendar API (raw CRUD)	Scheduling API (workflow)
List events	`GET /v3/grants/{grant_id}/events`	Handled inside the booking flow
Create an event	`POST /v3/grants/{grant_id}/events`	Written automatically on booking
Check who’s free	`POST /v3/grants/{grant_id}/calendars/free-busy`	`GET /v3/scheduling/availability` (per Configuration)
Offer bookable slots	You compute and render them	`POST /v3/grants/{grant_id}/scheduling/configurations` defines them
Confirm a booking	You write the event yourself	`POST /v3/scheduling/bookings`
Best for	Custom logic, full control over events	Appointment pages, fast booking flows

What is a calendar API and what can it do for a scheduling application?

A calendar API exposes direct read and write access to calendars and the events on them. For a scheduling application it answers two questions: what’s already booked, and where do new events go. You list events with GET /v3/grants/{grant_id}/events, create them with POST /v3/grants/{grant_id}/events, and check open windows with the Free/Busy endpoint, all against a connected account.

The calendar API is the right tool when your app owns the booking logic. You decide how slots are generated, what rules apply, and exactly how the event looks when it lands. The GET /v3/grants/{grant_id}/events call accepts a calendar_id query parameter and returns up to 50 events per page by default, so you read state, apply your own logic, then write back. One grant reaches Google, Microsoft, iCloud, and more through the same JSON shape, so you parse 1 response format instead of 4.

The request below lists events from a connected calendar. Use it to read current state before you decide whether a slot is open. The calendar_id parameter is required, and primary targets the account’s default calendar.

from nylas import Client

nylas = Client(api_key="<NYLAS_API_KEY>")

events = nylas.events.list(
    "<NYLAS_GRANT_ID>",
    query_params={"calendar_id": "primary", "limit": 50},
)

for event in events.data:
    print(event.title, event.when)

What is a scheduling API and how is it used in appointment-based applications?

A scheduling API runs the booking workflow so your app doesn’t have to. It computes real-time availability across one or more attendees, presents bookable slots, captures the chosen time, and writes the confirmed event to every calendar involved. This powers the “pick a time” page that turns a visitor into a confirmed meeting.

The Nylas scheduling endpoints split the work into three steps. First, POST /v3/grants/{grant_id}/scheduling/configurations defines a bookable Configuration: who hosts, how long meetings run, and the rules that gate availability. Then GET /v3/scheduling/availability returns open slots for that Configuration in real time. Finally, POST /v3/scheduling/bookings confirms the slot and writes the event. The bookings step also handles confirmation and cancellation, including the PUT /v3/scheduling/bookings/{booking_id} request an organizer uses to confirm or cancel a pending booking.

This call creates the Configuration that everything else hangs off. You set it up once per booking type, then reuse it for every visitor who books that meeting. It returns a configuration_id you pass to the availability and bookings calls.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "participants": [
      { "email": "[email protected]", "is_organizer": true }
    ],
    "availability": { "duration_minutes": 30 },
    "event_booking": { "title": "Intro call" }
  }'

When should you use each one?

Use the calendar API when your application owns the booking logic and needs full control over how events are read and written. Use the scheduling API when you want a ready-made booking flow and don’t want to rebuild availability math, slot rendering, and double-booking checks yourself. It comes down to how much you delegate.

Reach for raw event CRUD when slots follow custom rules, when events carry app-specific metadata, or when scheduling is one small piece of a larger calendar feature. A Free/Busy lookup plus your own logic gives you that. Reach for the scheduling layer when you’re building an appointment page, a sales-demo booker, or a support-call scheduler, where the goal is “confirmed meeting in under 60 seconds” and the booking flow is the product. Here’s the honest tradeoff: if your slot rules are unusual enough that a Configuration can’t express them, the calendar API plus the availability endpoint keeps you in control, at the cost of writing the booking flow yourself.

How do you prevent double-booking with each approach?

The scheduling API guards against double-booking for you: it re-checks availability at confirmation time, so a slot that filled while a visitor hesitated gets rejected before the event is written. With the calendar API you run that check yourself by calling POST /v3/grants/{grant_id}/calendars/free-busy right before you create the event, then writing only if the window is still clear.

Both paths lean on the same underlying Free/Busy data, which is available for every provider except iCloud. The difference is who orchestrates the check. The scheduling layer does it inside POST /v3/scheduling/bookings, closing most of the race-condition gap automatically. With raw CRUD, you own the window between reading availability and writing the event, so keep that gap as short as possible and re-read Free/Busy immediately before the create call. For the full pattern, including handling concurrent requests, see prevent double-booking.

What’s next

Check availability to compute open slots across attendees with the calendar API
Prevent double-booking for the race-condition pattern on both approaches
Scheduling API alternatives to compare the booking layer against other options
Getting started with Nylas to create a project, connector, and your first grant