Versioning

The path carries the major version

All routes are under /v1. Within /v1 the API changes only by addition:

• new routes and new optional parameters,
• new response members,
• new collections, aliases, bands, units and indices.

Lean v1 is the first part of /v1, not a separate version. It uses the same paths, ids, band names, parameters and error format as the full contract, so each later phase only adds to it.

Clients must ignore response members they do not know. That is what lets the API add them.

What never changes within /v1

Schema v1 lists what may never change while /v1 lives:

• collection ids, band names and common-name mappings,
• unified mask class ids and bit positions,
• harmonization ids and unit ids,
• any default whose change would alter returned values.

Breaking changes

A breaking change means /v2, announced at least 12 months before /v1 stops. During that time /v1 responses carry:

• a Deprecation header (RFC 9745) with the date the deprecation took effect,
• a Sunset header (RFC 8594) with the shutdown date,
• a Link header with rel="deprecation" pointing at the migration guide.

The same applies to a single route retired within /v1, such as an alias that upstream withdraws. The OpenAPI document marks deprecated operations with deprecated: true, and the changelog records every change with its date.

Version numbers you can read

Number	Where	Meaning
info.version	/v1/openapi.json	The OpenAPI document’s semantic version. The minor number rises with each additive release.
schemaVersion	/v1/schema	The schema v1 release, 1.0.0 at launch.
version	GET /v1/health	The deployed build.

Render version

Coming later When a fix changes the pixels a preset produces, a render version rises, every tile cache key changes at once, and TileJSON’s version member reports the new value. That is a bug fix, not a breaking change, because the request contract is unchanged.

The older hosts

stac.satellitedata.net and tiles.satellitedata.net keep working unchanged. They sit outside this contract: their requests and responses are those of the software behind them (Earth Search’s STAC API and TiTiler) plus the download API.