Versioning

Sometimes it is necessary to make backwards-incompatible (breaking) changes as new functionality and improvements are added to the Gigs API. Gigs guarantees that breaking changes will be released as part of a new major API version, leaving existing major versions backwards compatible and allowing existing clients to upgrade as and when they're ready.

Gigs API versions follow the format <major>.<minor>, where <major> is a date (e.g. 2026-01-29) and <minor> is an incrementing integer (e.g. 42). The minor version is incremented whenever a backwards-compatible (non-breaking) change is made, and is only tracked for record keeping purposes (and to aid in debugging efforts).

Backwards-compatible (non-breaking) changes

The following changes are considered to be backwards-compatible, and will be released to all major API versions (accompanied by a minor version increment):

Adding a new optional parameter to an existing request: New optional parameters might be added to existing requests, ensuring that clients that don't specify them will maintain the same behavior as before they were introduced.
Changing a required request parameter to optional: An existing request parameter can be relaxed from required to optional without affecting clients that were already providing a value for it.
Adding a new property to an existing response: New properties might be added to existing responses, ensuring that they don't modify the semantics of any other existing properties.
Adding a new error code: Error codes can be expanded to describe new situations. Your code should handle unknown error codes gracefully.
Changing an error message: Error messages are intended for human consumption and should not be used for error handling. Use error codes instead.
Changing the length or format of IDs: IDs should be treated as case-sensitive opaque strings and their format is subject to change. You can safely assume that they will never exceed 64 characters.
Adding or removing values from an enum: Enums should be treated as open, and changes to enum values in both requests and responses are seen as non-breaking. The only exception is removing a value from a request schema, which is considered a breaking change as existing clients may still be sending it.

Previews

Some functionality on our API is only available as a preview and doesn't offer the same stability guarantees described above. This will be clearly warned in the corresponding documentation. Breaking changes for such functionality are not only allowed but must be expected.

API request and response versioning

The API version determines the schema used for API requests and responses, and in some cases it could also impact the business logic applied by the Gigs platform.

To allow for easily and flexibly upgrading to newer API versions, clients specify the desired major API version for each request using the Gigs-Version header (e.g. Gigs-Version: 2026-01-29). Note that only the major version may be specified, and the latest applicable minor version will always be used.

If the Gigs-Version header is not set, the API will default to the latest available version at the time that the project was created. To see which version this is for your project, note the value of the Gigs-Version header in any response from the Gigs API. It is strongly suggested to specify the Gigs-Version header on every request.

Webhook versioning

The schema used for webhooks published by the Gigs platform is governed by the same API versioning framework.

The version used is set for each webhook endpoint. By default, the latest version at the time that the endpoint is created is used, but any version can be chosen when creating the endpoint.

The following steps are recommended for upgrading the version used for a webhook receiver:

Ensure that the logic in the service consuming webhooks is idempotent, and can safely receive a single webhook more than once.
Update the logic in the service consuming webhooks to be able to handle both the old and new schemas of the relevant events.
Create a new endpoint with the desired upgraded version. Keep all other settings the same.
Once you have confirmed that the new version of the events are being consumed successfully, delete the endpoint using the old version.
Update the logic in the service consuming webhooks to remove any reference to the old (and now unused) version.

Backwards-compatible (non-breaking) changes

The following changes are considered to be backwards-compatible, and will be released to all major API versions (accompanied by a minor version increment):

Adding a new optional parameter to an existing request: New optional parameters might be added to existing requests, ensuring that clients that don't specify them will maintain the same behavior as before they were introduced.

Changing a required request parameter to optional: An existing request parameter can be relaxed from required to optional without affecting clients that were already providing a value for it.

Adding a new property to an existing response: New properties might be added to existing responses, ensuring that they don't modify the semantics of any other existing properties.

Adding a new error code: Error codes can be expanded to describe new situations. Your code should handle unknown error codes gracefully.

Changing an error message: Error messages are intended for human consumption and should not be used for error handling. Use error codes instead.

Changing the length or format of IDs: IDs should be treated as case-sensitive opaque strings and their format is subject to change. You can safely assume that they will never exceed 64 characters.

Adding or removing values from an enum: Enums should be treated as open, and changes to enum values in both requests and responses are seen as non-breaking. The only exception is removing a value from a request schema, which is considered a breaking change as existing clients may still be sending it.

API request and response versioning

The API version determines the schema used for API requests and responses, and in some cases it could also impact the business logic applied by the Gigs platform.

Webhook versioning

The schema used for webhooks published by the Gigs platform is governed by the same API versioning framework.

The version used is set for each webhook endpoint. By default, the latest version at the time that the endpoint is created is used, but any version can be chosen when creating the endpoint.

The following steps are recommended for upgrading the version used for a webhook receiver:

Ensure that the logic in the service consuming webhooks is idempotent, and can safely receive a single webhook more than once.

Update the logic in the service consuming webhooks to be able to handle both the old and new schemas of the relevant events.

Create a new endpoint with the desired upgraded version. Keep all other settings the same.

Once you have confirmed that the new version of the events are being consumed successfully, delete the endpoint using the old version.

Update the logic in the service consuming webhooks to remove any reference to the old (and now unused) version.