Versioning and deprecation
How the Raster REST API is versioned with the Api-Version header, how long a version is supported, and the Deprecation and Sunset headers that announce a retirement.
The Raster REST API is versioned per request. This page is the policy an integration can rely on.
Pinning a version
Send an Api-Version header holding a date string on every request:
GET /organizations/acme/libraries HTTP/1.1
Host: api.raster.app
Authorization: Bearer <apiKey>
Api-Version: 2026-07-08The header is required; a request without it returns
API_VERSION_REQUIRED.
Every response carries Vary: Api-Version, so caches key bodies per version.
Pin an explicit version in your client.
The REST API is in Alpha. Until the Beta release, every Api-Version value
receives the current behavior, so a breaking change reaches every integration.
Follow the changelog.
Support window
A version is served until it is sunset. Before that happens:
- Announcement. The version is marked deprecated in the changelog, and every response to a request pinning it starts carrying the headers below.
- Notice period. At least 180 days pass between the announcement and the sunset date.
- Sunset. After the sunset date, requests pinning that version are rejected.
A retirement always appears in live response headers first, so an integration that watches its own headers sees one coming.
Deprecation headers
While a pinned version is deprecated, every response to it carries:
| Header | Standard | Example |
|---|---|---|
Deprecation | RFC 9745 | Deprecation: @1772409600 |
Sunset | RFC 8594 | Sunset: Tue, 15 Sep 2026 00:00:00 GMT |
Link | RFC 8288 | Link: <https://raster.app/docs/api/rest/changelog>; rel="deprecation" |
Deprecation is when the retirement was announced, as a structured-field date
(@ followed by Unix seconds, per RFC 9745). Sunset is when the version stops
being served, as an HTTP-date. The Link points at the migration notes. A
supported version carries none of the three — treat a response carrying Sunset
as a prompt to raise the pin.
Checking from a client
curl -sI https://api.raster.app/organizations/acme/libraries \
-H "Authorization: Bearer $RASTER_API_KEY" \
-H "Api-Version: 2026-07-08" \
| grep -i -E 'deprecation|sunset'Empty output means the pinned version is supported.
Currently deprecated versions
None. Every published version is supported.