Versioning and upgrades

The API version is in the URL.

https://api.askylabs.com/v1/brands

Your integration is pinned by the path it calls. Nothing changes underneath you until you change that path, so there is no version header to set and no account-level version to keep track of.

What we may change within v1

These are additive changes. They ship continuously, without notice, and your integration must tolerate them.

• New endpoints
• New fields on existing response objects
• New optional query parameters
• New values in an enumerated field, such as a new AI engine or a new opportunity type
• New error codes within an existing HTTP status

Handle unknown enum values too. If you switch on engine and we add one, the sensible default is to pass it through or skip it, not to throw.

What counts as breaking

These would not ship inside v1. They require a new version.

• Removing an endpoint, a field, or a query parameter
• Renaming anything
• Changing a field’s type, or the meaning of an existing value
• Changing a default, such as the page size
• Adding a required parameter to an existing endpoint
• Tightening validation so a previously accepted request is refused

How a new version would work

If we introduce v2, both versions run side by side. v1 continues to serve your integration unchanged while you migrate on your own schedule, and you migrate by changing the path, one endpoint at a time if you prefer, since the versions are independent.

We would publish what changed and why, a mapping from each v1 endpoint to its v2 equivalent, and a deprecation timeline with a minimum of 12 months of continued v1 support from the announcement. Deprecated endpoints also return a Deprecation header with the sunset date, so you can detect them from your own logs rather than tracking our announcements.

Watching for changes

• The changelog below records every additive change.
• The OpenAPI specification  is generated from the definitions that serve the API. Diffing it between deploys is a reliable way to catch new fields and endpoints programmatically.

Building an integration that survives

A few habits that make version changes uneventful:

Select the fields you need. Store the fields your integration uses rather than mirroring whole response objects into your warehouse schema. New fields then never require a schema migration on your side.

Do not depend on field order or on the number of keys in an object. Neither is part of the contract.

Do not parse identifiers. Ids are opaque strings. Their length and internal format may change.

Do not depend on pagination cursors being stable across versions. A cursor is valid only for continuing the list you were walking. See pagination.

Pin the version, not the host. Call https://api.askylabs.com/v1/... rather than constructing the path from configuration that might drift.

Changelog

Changes to v1, newest first.