Versioning & lifecycle

The Titan Public API uses path-based major versioning and surfaces lifecycle state directly on each operation.

How majors work

Each major lives at its own path prefix. Today the public surface is /public/v1/...; additional majors appear at their own path prefixes as they ship.

There is no global version dropdown — pick a major by URL. At most two GA-track majors coexist at any time (one current, one being deprecated); older majors move to sunset and eventually retired.

Inside a major, changes are additive only: new optional fields and new endpoints may appear; nothing that already exists changes shape. A breaking change ships as a new major.

Pinning within a major (optional)

Send the Titan-API-Version header to pin to a specific SemVer minor/patch:

curl https://titanapi.securityscorecard.io/public/v1/observations \
  -H "Authorization: Bearer $TITAN_API_TOKEN" \
  -H "Titan-API-Version: 1.2.0"

Format: three-segment SemVer (MAJOR.MINOR.PATCH).
MAJOR must match the major in the URL path — mismatched pairs are rejected with 400.
Omitting the header returns the latest minor/patch within the URL major. Recommended for most callers.
When to pin — regression-sensitive systems, contract tests, long-lived batch jobs. Do not pin without a plan to unpin.

Lifecycle signals

Every operation moves through a stage state machine. The current stage is shown as a stability badge on the operation page.

Stage	Meaning
`alpha`	Earliest stage. Shape may change without notice; not intended for production use.
`beta`	Open to all customers but the shape may still change in backwards-incompatible ways.
`stable`	Backwards-compatible changes only. Safe for production.
`deprecated`	Still works, but a sunset date has been published. Migrate before then.
`sunset-pending`	Final wind-down. Retirement is imminent.
`retired`	Endpoint is gone. The gateway returns `410 Gone`.

When an operation enters deprecated, the operation page shows:

Deprecation date — when the public commitment to retire was published.
Sunset date — when the gateway will return 410 Gone. Minimum 12 months after deprecation.
Replacement — a link to the successor operation or migration guide.

Wire signals

Deprecated operations send standard HTTP headers on every call:

Deprecation: true
Sunset: <HTTP-date> — the date the gateway will return 410 Gone.
Link: <successor-url>; rel="successor-version" — the replacement endpoint.

After the sunset date, requests return 410 Gone. Retirement is irreversible.

Lifecycle extensions

Lifecycle state is encoded in the OpenAPI overlay:

Extension key	Purpose
`x-stability`	One of the six stages above
`x-version`	SemVer string for documentation
`x-deprecated-at`	ISO date the operation was marked deprecated
`x-sunset-at`	ISO date the gateway will return `410 Gone`
`x-replacement`	Docs URL or API path of the successor