GuidesAPI ReferenceChangelog
Log In

Change Management

API Change Management

In order to continue adding functionality, we regularly make improvements and changes to our API.

Backwards Compatible Changes

We consider the following types of changes to be backwards compatible. You should ensure your code is robust enough to gracefully handle the following changes:

  • Adding new API resources.
  • Adding new optional request parameters to existing API methods, using sensible defaults if not present in requests.
  • Adding new fields to existing API responses.
  • Changing the order of fields in existing API responses.
  • Changing the length or format of opaque strings, such as object IDs, error messages, and human-readable strings.
  • Adding new values to an existing enum.

Versioned Changes

When we make backwards-incompatible changes to the API we will release a new dated version. Changes and upgrade instructions will be detailed in the Changelog.

You must send a Pinwheel-Version header with each request to specify how the Pinwheel API should behave. See Version Headers on the API page for more information.

Old versions are considered deprecated and will be sunsetted when no more API requests are made to them. Trying to use a sunsetted version will result in a 400 Bad Request error.

New dated versions, and plans to deprecate or sunset a version, will be communicated to you by our customer success team. They will also be detailed in the Changelog.

You can access docs for deprecated API versions via the dropdown in the top bar (e.g., "v2021-07-28").

Webhook Versions

We will also release a new dated version when we make backwards-incompatible changes to our webhook events. This policy began with v2023-04-18. You can access webhook event docs for each API version via the dropdown in the top bar (e.g., "v2021-07-28"). For more information on creating webhooks with a specified version, see the Webhooks guide.

Terminology

Deprecated: usage is discouraged.

Sunsetted: discontinued, no longer available for usage.

Please contact [email protected] for access to our Developer Dashboard.