Feature Gates
Saturday’s API features progress through launch stages. The stage controls a feature’s visibility, who can reach it, and what stability you can expect from it.
Features ship at different times: some are in early access (alpha), some in public beta, and some stable (GA). If an endpoint returns a 404 when you expect it to work, check the feature stage: it may be in STEALTH or require alpha access.
Launch stages
STEALTH
A stealth feature is invisible. The endpoint returns a 404 byte-identical to a request for a path that doesn’t exist: same body, same headers. The request never reaches authentication, CORS, or request logging, so no timing or header difference distinguishes a gated endpoint from a nonexistent one.
ALPHA
Alpha features are available to partners who have been invited. Reaching an alpha feature without being on the allowlist returns a 403:
The response carries X-Saturday-Feature-Stage: ALPHA whether or not you are on the allowlist. On the allowlist, it also carries the notice header:
BETA
Beta features work for all authenticated partners. Responses include:
GA (General Availability)
GA features are production-stable with backward compatibility guarantees. Breaking changes go through a deprecation cycle.
DEPRECATED
Deprecated features still work but will be removed. Responses carry:
The Deprecation header carries true. Sunset dates are announced per feature; ask at api@saturday.fit if a feature you depend on is marked deprecated.
The feature keys
Six keys gate REST routes. Each covers the routes listed beside it.
products, knowledge and athlete_insights gate their MCP tools as well as their REST routes, with the same rule: at ALPHA a tool appears only for partners on the feature’s alpha allowlist (see MCP Integration). Two more keys gate MCP tools rather than REST routes: coach (the coach tools, which also require a coach principal on the request) and bottling (build_bottling_plan and record_bottling_choice). Neither has a shipped default, so each is STEALTH until set in configuration.
The right-hand column is the default the gateway falls back to, not a statement about production. Each environment stores stages in configuration, and a per-partner override can raise a single partner above the global stage. Read GET /v1/ for what your key can reach today.
Feature groups
Features are grouped so a stage transition can move several at once:
Getting alpha access
Alpha access is by invitation. To request access:
- Email api@saturday.fit with your platform name, use case, and expected volume
- Saturday reviews the request and adds your partner ID to the alpha allowlist
- Within 5 minutes, your API key works on alpha-stage endpoints
Alpha partners get early access to new features before public beta, a direct support channel for integration questions, and a say in API design decisions. There is no additional cost.
Checking feature availability
The API root endpoint shows what your key can reach:
The response lists the reachable endpoints, marking alpha-stage ones. Features in STEALTH are omitted from discovery, from the error catalog, and from this documentation.
