API Contract Guarantees

This page defines what partners can rely on when integrating with the Sleeved API: which changes Sleeved considers safe to ship without warning, which changes require advance notice, and how long that notice period is.

If you read nothing else: /v1 endpoints are stable, additive changes ship without notice, breaking changes ship through /v2 with at least 6 months of overlap and Deprecation + Sunset response headers on the /v1 endpoints.

Versioning

All public API routes are prefixed with a major version: /v1, /v2, etc. The current version is /v1.

• The version prefix is part of the URL. There is no Accept header content negotiation; the version is determined by the URL path.
• The OpenAPI spec's info.version field tracks the major + minor + patch shape (1.0.0 today). Patch and minor bumps are additive and do not change the URL prefix; major bumps move to a new URL prefix (/v2).
• New games added to the public allowlist are additive. They do not trigger a new major version.

Additive vs Breaking Changes

The following changes are additive and may ship without notice:

• New endpoints added under the current version prefix
• New optional request fields, query parameters, or headers
• New optional response fields
• New enum values in response payloads (for fields whose enums are documented as open-ended — e.g. game slugs as new games are onboarded)
• New error subcodes or finer-grained error messages, as long as the existing error string and status code are still produced for the same condition
• New examples or documentation prose in the OpenAPI spec
• Performance improvements that do not change response shape

The following changes are breaking and require advance notice (see Deprecation Timeline):

• Removing an endpoint, response field, or query parameter
• Renaming a field or operationId
• Changing a field's type, format, or null-tolerance
• Narrowing the set of accepted values for a request field, query parameter, or path parameter
• Adding a new required request field
• Removing an enum value from a response or changing its meaning
• Changing the URL of an existing endpoint (including version-prefix changes — see /v2 precedent below)
• Changing the meaning of an existing status code on an existing endpoint

If you are unsure whether a planned change is additive or breaking from your integration's perspective, write engineering@endlessgalaxy.dev before deploying against it.

Deprecation Timeline

When a breaking change ships, the old behavior remains available for at least 6 months from the announcement date. During the deprecation window:

• The deprecated endpoint or field continues to work and return correct responses
• The deprecated endpoint emits an RFC 8594 Deprecation response header containing the date deprecation was announced
• The deprecated endpoint emits a Sunset response header containing the date after which it will stop working
• The replacement endpoint or field is documented with a migration link from the deprecated entry's documentation

Example response headers on a deprecated endpoint:

Deprecation: Sun, 01 Jan 2026 00:00:00 GMT
Sunset: Wed, 01 Jul 2026 00:00:00 GMT
Link: <https://docs.sleeved.gg/api/contract-guarantees>; rel="sunset"

Partners are notified by email at the announcement and again 30 days before sunset. The current public changelog is also updated.

/v2 Precedent

When /v2 ships, all /v1 endpoints continue to work for the full 6-month deprecation window — partners are not forced to migrate every endpoint at once.

Sleeved uses per-endpoint coexistence for the major-version transition: /v1/games/{slug}/cards and /v2/games/{slug}/cards may serve different shapes simultaneously during the transition window. This means partners can migrate one endpoint at a time rather than rewriting their entire integration in a single deploy.

The transition shape is:

1. /v2 is announced. All /v1 endpoints remain unchanged for the full deprecation window.
2. /v1 endpoints begin emitting Deprecation and Sunset headers pointing to their /v2 equivalents.
3. After the sunset date, /v1 endpoints are removed.

Game additions and removals do not trigger /v2. The game allowlist is part of the /v1 contract; new games appear in /v1/games/{slug}/... paths additively.

Game Allowlist Policy

The set of games available via the public API is governed by PUBLIC_API_GAME_SLUGS (canonical source: packages/lib/src/games.ts). The current allowlist is published in the API overview.

• Adding a game is additive. New games appear under existing endpoints (/v1/games/{newSlug}/cards, etc.) without a version bump.
• Removing a game is breaking. A game removal goes through the deprecation timeline above: 6 months of Deprecation/Sunset headers on the affected paths, with the removal date announced in advance.
• Internal/playtest games (e.g. chrono-core-playtest) are intentionally excluded from the allowlist and are not part of the contract. They may appear and disappear without notice.

Status Codes Contract

The following status codes are stable parts of the contract — partner SDKs may switch on them:

Within the stable categories, the body error string is also stable for the documented cases. See Authentication for the three authentication error shapes and Rate Limiting for the 429 retry contract.

We may add new 4xx subcodes (e.g., a more specific 422-style validation error) as additive changes — the existing 400 path continues to be produced for the same conditions.

Pagination Contract

Cursor pagination on browseCards follows these rules:

• Cursors are opaque. Do not parse them, base64-decode them, or assume any internal structure. The cursor format may change between versions or even within a single version (cursors are server-generated and partner-consumed only).
• Cursors expire. A cursor is valid for the same parameters that produced it (game slug, hitsPerPage). Restarting pagination with a different hitsPerPage invalidates any stored cursor — request a fresh page-1 instead.
• Cursors are not stable across resyncs. A cursor returned today may not be valid tomorrow if the underlying index has been rebuilt. If you receive a 400 with a cursor-related error, restart pagination from page 1.
• Ordering is stable within a single pagination walk (start at page 1, follow cursors to the end). The order is not guaranteed to be stable across separate pagination walks — the underlying Algolia index may reorder records between walks. If your integration depends on a specific order across runs, sort the results client-side after collection.
• Adding fields to hits is additive. New fields may appear in hits[i] records without notice; existing fields keep their shape and meaning per the breaking-change rules above.

What Is NOT Part of the Contract

The following are not stable and may change without notice:

• The internal storage path scheme for card images (the cardImageUrl field is stable; the URL it contains may change CDN, bucket, or path layout)
• Internal log format, including the reason=missing|not_found|revoked operator-side log distinctions
• The exact wording of human-readable error messages outside the documented set in Authentication and Rate Limiting — partners should switch on status code + the documented error strings, not on free-text error prose
• Performance characteristics (latency, throughput, exact cache TTLs), as long as documented rate-limit quotas are honored
• Internal Sleeved-specific endpoints under paths other than /v1 (or future /v2) — those are not part of the partner API
• The fumadocs-openapi rendering of these docs (UI may change without contract impact)

Reporting Contract Violations

If you observe behaviour that contradicts a guarantee on this page — a breaking change shipped without notice, a Deprecation header missing on a now-deprecated endpoint, a status code changing meaning — please write engineering@endlessgalaxy.dev with the request you sent, the response you received, and the contract clause you believe was violated. Sleeved treats contract regressions as bugs, not negotiable trade-offs.