After several months of preview as an [Alpha](/content/docs/compliance/alpha-beta/index.html) product, we are pleased to announce that [Medplum's Scheduling API](/content/docs/scheduling/index.html) has graduated to [Beta](/content/docs/compliance/alpha-beta/index.html).

Medplum's Scheduling API provides an interface for applications to atomically interact with [Schedule](/content/docs/api/fhir/resources/schedule/index.html), [Slot](/content/docs/api/fhir/resources/slot/index.html), and [Appointment](/content/docs/api/fhir/resources/appointment/index.html) resources to safely create and manage bookings without creating scheduling conflicts. Developing a feature like this required the ability to iterate as we learned, and our Alpha period provided exactly that.

## What changed during Alpha [​](/content/blog/scheduling-beta#what-changed-during-alpha/index.html)

We made some breaking changes over the course of the Alpha period to simplify the API surface and support multi-resource scheduling:

- **Removed `Schedule/:id/$find`**: This route has been replaced by `Appointment/$find`, which handles single-Schedule lookups as a basic case of its ability to query multiple Schedules at once.
- **Removed slot-based `Appointment/$book`**: The `slot` parameter input to `$book` has been removed. The operation now only accepts an `appointment` as input, which can act as a container for the potentially many Slot resources involved in a single atomic booking operation.
- **`HealthcareService` as required service type**: Our original specification considered using [ActivityDefinition](/content/docs/api/fhir/resources/activitydefinition/index.html) resources as an optional place to store shared service type definitions. After considering the impact it would have when booking appointments with several participants, we decided to require that service types be explicitly defined as [`HealthcareService`](/content/docs/api/fhir/resources/healthcareservice/index.html) resources, and a reference to such a healthcare service must be included to search for available appointments in `$find`.
- **Changed `availability` format**: We've chosen a storage format for customizing availability that mirrors the [FHIR R5 Availability type](https://hl7.org/fhir/R5/metadatatypes.html#Availability). This will let us migrate these definitions easily when Medplum Server adds support for later FHIR releases.

## The Beta API surface [​](/content/blog/scheduling-beta#the-beta-api-surface/index.html)

The Beta API consists of five operations:

| Operation | Description |
| --- | --- |
| [`Appointment/$find`](/content/docs/scheduling/appointment-find/index.html) | Find available slots across one or more Schedules |
| [`Appointment/$book`](/content/docs/scheduling/appointment-book/index.html) | Book an appointment in one step |
| [`Appointment/$hold`](/content/docs/scheduling/appointment-hold/index.html) | Temporarily hold a slot |
| [`Appointment/$confirm`](/content/docs/scheduling/appointment-confirm/index.html) | Confirm a held appointment |
| [`Appointment/$cancel`](/content/docs/scheduling/appointment-cancel/index.html) | Cancel an appointment |

## What Beta means [​](/content/blog/scheduling-beta#what-beta-means/index.html)

The core API contract is now stable. Breaking changes are still possible during Beta, but we will note them in release notes and provide a migration path where practical. The API is appropriate for production use in non-critical workflows. See our [Alpha & Beta policy](/content/docs/compliance/alpha-beta/index.html) for the full details.

## Get started [​](/content/blog/scheduling-beta#get-started/index.html)

Check out the [Scheduling documentation](/content/docs/scheduling/index.html) for a full reference, including how to define availability, find open slots, and book appointments.

Thank you to all our partners who experimented with the API during the Alpha period and provided such valuable feedback!

- [What changed during Alpha](/content/blog/scheduling-beta#what-changed-during-alpha/index.html)
- [The Beta API surface](/content/blog/scheduling-beta#the-beta-api-surface/index.html)
- [What Beta means](/content/blog/scheduling-beta#what-beta-means/index.html)
- [Get started](/content/blog/scheduling-beta#get-started/index.html)