Versioning

At Healthie, we’re committed to providing a stable and reliable API for all our integrations. Our versioning strategy allows us to continuously improve our API while ensuring your existing integrations remain functional.

How We Release Changes

We release two types of changes to the Healthie API:

Breaking Changes (Require Version Upgrade)

When we make breaking changes, we release a new API version. You must update your Healthie-GraphQL-API-Version header to access these changes. This gives you complete control over when to adopt breaking changes, ensuring they never affect your integration unexpectedly.

Non-Breaking Changes (Automatic)

We continuously add new fields, queries, mutations, and optional arguments through accretion. These changes are immediately available in all API versions, including your current version, without any action required. You don’t need to update your version header to access these improvements.

Understanding Breaking Changes

A breaking change is any modification that could cause existing API calls to fail or return different results without any changes to your account data. We take breaking changes seriously and use versioning to ensure they never affect your integration unexpectedly.

Examples of breaking changes (which require a new version):

• Removing a field
• Changing the return type of a field
• Changing an input argument default (e.g changing a query to be default unpaginated versus paginated)
• Making a field nullable when it was previously non-nullable
• Making an input argument non-nullable when it was previously nullable (e.g. id: ID -> id: ID!)
• Making a field nullable when it was previously non-nullable (e.g. user: User! -> user: User)

Examples of non-breaking changes (which we can make without a new version):

• Adding new queries, mutations, or fields
• Adding an optional new input argument to an existing mutation
• Adding a new filter or sort_by option to an existing field
• Adding new and updated data to Healthie-provided resource queries (e.g Insurance Plans or Icd Codes)
• Fixing an internal server error (e.g a 500)

When we need to make breaking changes, we release a new API version. This allows you to continue using your current version while giving you the option to adopt the new changes when you’re ready.

What is API Versioning?

API versioning is a strategy that allows us to make significant improvements to our API while protecting your existing integrations. Different versions of our API can exist simultaneously, giving you control over when to adopt new changes. This approach ensures we can continue evolving our API while maintaining stability for all our users.

When will Healthie release a new version?

When we make updates to the GraphQL API that may result in a breaking change, a new version is created. Each version is carefully documented and includes all the modifications made since the last version. By opting into a specific version, you can control when and how you adopt new features and changes, eliminating the risk of breaking your existing integration.

All API versions are cumulative, which means that changes in version N+1 will include all changes from version N. Customers that request the latest version will need to update their API clients as we release new versions.

We seek to avoid breaking changes and will continue to make non-breaking updates and improvements through accretion. This means you won't need to opt-in to use these changes, as they will be available in all versions, including the baseline.

Specifying an API Version

curl \
-H "Healthie-GraphQL-API-Version: 2024-06-01" \
-H 'AuthorizationSource: API' \
-H 'Authorization: Bearer ...' \
-d '{...}' https://api.gethealthie.com/graphql

You should use the Healthie-GraphQL-API-Version header to specify an API version, as shown in following example.

Requests without the Healthie-GraphQL-API-Version header will default to use the 2024-06-01 version (baseline).

How to adopt a new version

1. Review Changes: Check the changelog below for updates in the latest version. Use the GraphQL Explorer and check our Schema Reference to find the latest schema definitions for the version you are adopting.
2. Test: Try the new version in your development environment to ensure compatibility
3. Update: Change your API requests to use the new version header
4. Deploy: Roll out your updated integration with confidence

Version History (Breaking Changes)

These changes require opting into a specific API version using the Healthie-GraphQL-API-Version header.

2025-10-15

• Removed clientMutationId from all mutations
• Completed Connection Type pagination migration for remaining query fields

2025-07-31

• Standardized field types: converted string fields to enums and integers for improved type safety

2025-05-15

• Added validation to createAppointment to allow only a single attendee for individual appointments when specified via attendee_ids (user_id is still preferred for individual appointments)

2025-04-01

• Converted fields and arguments to enums for improved type safety
• Added validation to require appointment_location_id when scheduling an in-person appointment via createAppointment

2025-01-01

• Migrated fields to Connection Type pagination

2024-11-01

• Added validation and updated field nullability for common mutations
• Fixed spelling issues across the API

2024-10-20

• Updated ISO8601Date and ISO8601DateTime type implementations

2024-10-01

• Added pagination to the pharmacies query field

2024-07-01

• Standardized datetime fields to ISO8601DateTime type (previously String)
• Standardized ID fields to ID type (previously String and Int)