API Stability Policy

This page documents Symbol's commitments around API change. It complements the Preview API document, which covers versioning mechanics; this page covers promises about how that versioning is used.

Current status

Symbol's HTTP API is in preview. Every public resource endpoint is served under /api/preview/*. There is no /api/v1/* yet — preview is the current version, not a beta running alongside a stable release.

Preview access is free. There is no paid tier today. Anyone with a Symbol account can create an API key and integrate against /api/preview/* at no cost. Preview users self-select as early adopters who accept aggressive iteration in exchange for shaping the contract; the trade-off is a shorter notice window for breaking changes (see Notice periods below). When /api/v1/* ships, it will be the stable, long-deprecation-window contract; pricing for v1+ is to be determined and will be announced on the changelog before it takes effect.

What "breaking change" means

A change is breaking if a previously-correct integration could begin returning errors, missing data, or different semantic results without any client-side change. In particular:

• Removing or renaming a field, route, query parameter, or error code.
• Tightening request validation (e.g. a previously-optional field becoming required, a regex narrowing what's accepted).
• Changing the type of a field (string → number, scalar → array).
• Changing the HTTP status code an endpoint returns for a given input.
• Changing semantics so the same input produces a different effect (e.g. a sort order silently flipping).
• Removing or renaming a problem-type URI in an error response.

A change is not breaking when it is purely additive or relaxing:

• Adding a new optional request field, a new endpoint, or a new optional query parameter.
• Adding a new enum value that only appears on output (an output enum widening is breaking if a client matched on a closed set; we treat output enums as open by default and document any closed enum explicitly).
• Loosening validation (a previously-required field becoming optional, a regex widening).
• Cosmetic changes to OpenAPI descriptions, examples, summaries, or tags. These appear in the changelog as cosmetic and never require notice.

Notice periods

The 14-day floor for preview is a hard commitment, not a target. Symbol will not ship a breaking change to /api/preview/* without a changelog entry that has been live for at least 14 calendar days and an email notification to all active API key holders sent at least 14 days before the change.

The 12-month commitment is a contract for stable versions — once v1 ships, breaking changes there require a year of advance notice published in the changelog, with the deprecated behaviour continuing to work unchanged for the entire window.

Versioning model recap

Versions coexist under different namespaces. Symbol does not replace routes in place. When a route is promoted, both paths live side-by-side during the deprecation window:

/api/preview/capsules/{id}   ← current; may diverge during preview
/api/v1/capsules/{id}        ← future stable; copied at promotion time

See Preview API → Versioning model for the full mechanics, including why URL == file location and why promotion is a deliberate copy rather than a rename.

Promotion criteria

Promotion of the preview surface to /api/v1/* is gated on the following objective criteria. All must hold concurrently before promotion is announced:

• All in-scope entities migrated. Every entity listed in the Preview API → What's in the preview namespace inventory has shipped its Zod contract module, OpenAPI emission, and generated-client coverage.
• 60-day schema-frozen window. No additions to the public surface for 60 consecutive days. Cosmetic-only changes are allowed.
• 30-day no-breaking-change streak. No breaking entries in the API changelog for 30 consecutive days immediately preceding the promotion announcement.
• Integration tests lock the contract. Every promoted route is covered by tests that assert the response shape byte-for-byte (no any-typed escape hatches in fixtures, no additionalProperties: true shortcuts on output schemas).
• Generated clients clean. The TypeScript and Dart generated clients build with zero diff against the previous release on a no-op regeneration.
• Public preview banners removed for promoted routes. Promotion flips x-preview from true to absent for each promoted operation and updates first-party clients in the same release.

Promotion is a deliberate, reviewable change in the operation registry that produces a new OpenAPI artifact and a new copy of the route file. The promotion announcement itself is a breaking-class changelog entry on the preview surface (because preview routes will eventually sunset) and an additive entry on v1.

How changes are announced

Symbol uses several parallel channels so that no integrator can plausibly claim they had no way to find out about a breaking change. A breaking change must appear on all of the channels marked required before the change ships.

API key holders can manage their notification preferences at Settings → API Keys. Email delivery uses the same address as the account's primary login. Symbol does not sell or share these addresses.

SLA

There is no formal uptime or latency SLA on preview. Symbol publishes status updates at the status page and aims for production-level reliability, but preview tier users do not have a contractual SLA to point to.

Rate limits

Preview routes are subject to per-API-key rate limits. The defaults and their headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After on 429) are documented in Preview API → Rate limits. Limits are not part of the breaking-change contract — Symbol may tune them up or down as preview load patterns become clearer, with changes recorded on the changelog as cosmetic.