Versioning

How the Skytells API is versioned — path-based versioning, backward compatibility, and deprecation policy.

API Versioning

The Skytells API is versioned through the URL path. The version identifier is embedded directly in the base URL.

The current and only stable version is v1:

https://api.skytells.ai/v1

All endpoints are accessed under the /v1 prefix:

https://api.skytells.ai/v1/models
https://api.skytells.ai/v1/predictions
https://api.skytells.ai/v1/predictions/{id}

The Edge API follows the same convention:

https://edge.skytells.ai/v1

Path-based versioning — The version is part of the URL (e.g., /v1/predictions). This makes it explicit which version you're targeting in every request.
Backward compatibility — Within a major version, we maintain backward compatibility. New fields may be added to responses, but existing fields will not be removed or changed in a breaking way.
Deprecation policy — If a new major version is introduced, the previous version will remain available for a transition period. Deprecation timelines will be communicated through the Skytells changelog and developer emails.

# v1 — current stable version
curl https://api.skytells.ai/v1/models \
  -H "x-api-key: $SKYTELLS_API_KEY"

Always include the version prefix in your API calls. Requests without a version (e.g., https://api.skytells.ai/models) are not supported.

Within v1, the following changes may happen without bumping the version:

Change	Breaking?
New fields added to response objects	No
New optional query parameters	No
New endpoints added	No
New enum values added to existing fields	No
Existing fields removed or renamed	Yes — requires new version
Response structure changes	Yes — requires new version
Required parameter changes	Yes — requires new version

Subscribe to the Skytells changelog for announcements on new versions and deprecations.
Monitor response headers for deprecation warnings when they are introduced.
If you use an official SDK, updates will handle version transitions for you.

How is this guide?