API fundamentals

This section covers conventions every endpoint follows, whichever capability you’re building with.

Requests #

Send each request to the API for your data center, shown as {data_center_url} in the examples.

Request bodies can be JSON or form encoded, though JSON is recommended. Set the Content-Type header to application/json; charset=utf-8 or application/x-www-form-urlencoded to match.

Compatibility #

We lean on existing standards, such as OAuth 2.0, OpenID Connect, and iCalendar, wherever we can, so integrations can use familiar tools.

We don’t make breaking changes to stable endpoints, but we do add to them. Parse responses permissively, ignoring any attributes your application doesn’t understand. New behavior is always opt-in, through optional parameters or a future version of the API.

Release statuses #

Most of the API is stable. Newer additions carry a release status, shown next to the endpoint’s title.

• Beta features are generally recently released or enhanced and are being closely monitored for performance under real-world conditions. They are stable from an interface perspective.
• Alpha features are new additions that haven’t been used in anger. We are confident that they work, but are aware they haven’t been hardened by real world usage. Whilst we do not expect to make any breaking changes once an addition to the API reaches this point, this may happen at some point in the future.
• Prerelease and Design documents describe features that need to be enabled by Cronofy support, or that are shared for discussion ahead of implementation, and are subject to change.
• Superseded endpoints still work, but have been replaced by a newer endpoint that the page links to. Use the replacement in new integrations.

Alpha features are available to use in production. If you are using one, please let us know so we can keep you informed of any changes.