API Stability and Versioning

LyftData classifies product API operations individually. Do not infer support from a raw route count or from a first-party source reference.

Operation metadata

The installed OpenAPI document can include these LyftData extensions:

Extension	Meaning
x-lyftdata-stability	Compatibility posture such as stable, compatibility, experimental, operator, internal, or debug
x-lyftdata-audience	Intended consumers such as ui, cli, operator, integration, worker, or generated-client
x-lyftdata-generated-client	Whether the operation is admitted to the curated generated-client subset
x-lyftdata-edition	Edition availability for the operation
x-lyftdata-auth-scope	Required product authorization scope where declared

Use stable operations for durable automation. Treat experimental operations as changeable and pin automation to a tested product release. operator operations are supported recovery or administration surfaces but can require elevated access. Do not integrate with internal or debug operations.

compatibility marks an old shape retained during migration. Move to its canonical replacement and do not start new integrations on the alias.

Generated clients

Generated-client inclusion is deliberately narrower than OpenAPI coverage. An operation can remain out of generated clients when it involves:

• WebSocket or long-lived stream setup;
• browser redirects such as OAuth callbacks;
• sensitive write-only values;
• experimental request/response schemas; or
• operator actions without a stable typed-client use case.

If an operation has x-lyftdata-generated-client: false, call it directly only when its audience and stability admit your use case. Do not hand-add it to a generated client and present that as a supported SDK contract.

Pagination, retries, and idempotency

Read the operation schema and response descriptions. LyftData does not make one global promise for pagination, retry safety, or mutation idempotency:

• pagination parameters and response cursors are operation-specific;
• retry GET requests only after considering load and consistency;
• retry mutations only when the operation documents an idempotency mechanism or when you can first inspect resulting state; and
• handle 202 Accepted as queued or pending work, not completed work.

Use bounded timeouts and exponential backoff for transient failures. Do not retry 400, 401, or 403 indefinitely.

Upgrade discipline

Before upgrading the server:

1. download the OpenAPI documents from the current and candidate releases;
2. diff the operations and schemas used by your automation;
3. test against the candidate with representative roles and tenants;
4. update generated clients from the candidate document where applicable; and
5. retain a rollback path for both server and automation.

The unversioned /api namespace follows the server release. The /integration/v1 namespace is additive within version 1, but consumers should still test new server releases for behavioral and availability changes.