{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Versioning & lifecycle"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"versioning--lifecycle","__idx":0},"children":["Versioning & lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Titan Public API uses ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["path-based major versioning"]}," and surfaces lifecycle state directly on each operation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-majors-work","__idx":1},"children":["How majors work"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each major lives at its own path prefix. Today the public surface is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/public/v1/..."]},"; additional majors appear at their own path prefixes as they ship."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no global version dropdown"]}," — pick a major by URL. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["At most two GA-track majors coexist"]}," at any time (one current, one being deprecated); older majors move to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sunset"]}," and eventually ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retired"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Inside a major, changes are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["additive only"]},": new optional fields and new endpoints may appear; nothing that already exists changes shape. A breaking change ships as a new major."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pinning-within-a-major-optional","__idx":2},"children":["Pinning within a major (optional)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Titan-API-Version"]}]}," header to pin to a specific SemVer minor/patch:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl https://titanapi.securityscorecard.io/public/v1/observations \\\n  -H \"Authorization: Bearer $TITAN_API_TOKEN\" \\\n  -H \"Titan-API-Version: 1.2.0\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Format:"]}," three-segment SemVer (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MAJOR.MINOR.PATCH"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MAJOR"]}]}," must match the major in the URL path — mismatched pairs are rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Omitting the header"]}," returns the latest minor/patch within the URL major. Recommended for most callers."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When to pin"]}," — regression-sensitive systems, contract tests, long-lived batch jobs. Do not pin without a plan to unpin."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"lifecycle-signals","__idx":3},"children":["Lifecycle signals"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every operation moves through a stage state machine. The current stage is shown as a stability badge on the operation page."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Stage"},"children":["Stage"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["alpha"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Earliest stage. Shape may change without notice; not intended for production use."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beta"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Open to all customers but the shape may still change in backwards-incompatible ways."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stable"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Backwards-compatible changes only. Safe for production."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deprecated"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Still works, but a sunset date has been published. Migrate before then."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sunset-pending"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Final wind-down. Retirement is imminent."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retired"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Endpoint is gone. The gateway returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["410 Gone"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"deprecation-banner","__idx":4},"children":["Deprecation banner"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When an operation enters ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deprecated"]},", the operation page shows:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Deprecation date"]}," — when the public commitment to retire was published."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sunset date"]}," — when the gateway will return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["410 Gone"]},". Minimum 12 months after deprecation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Replacement"]}," — a link to the successor operation or migration guide."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"wire-signals","__idx":5},"children":["Wire signals"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deprecated operations send standard HTTP headers on every call:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Deprecation: true"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Sunset: <HTTP-date>"]}," — the date the gateway will return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["410 Gone"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Link: <successor-url>; rel=\"successor-version\""]}," — the replacement endpoint."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After the sunset date, requests return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["410 Gone"]},". Retirement is irreversible."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"lifecycle-extensions","__idx":6},"children":["Lifecycle extensions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Lifecycle state is encoded in the OpenAPI overlay:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Extension key"},"children":["Extension key"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-stability"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One of the six stages above"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-version"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["SemVer string for documentation"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-deprecated-at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO date the operation was marked deprecated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-sunset-at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO date the gateway will return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["410 Gone"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-replacement"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Docs URL or API path of the successor"]}]}]}]}]}]},"headings":[{"value":"Versioning & lifecycle","id":"versioning--lifecycle","depth":1},{"value":"How majors work","id":"how-majors-work","depth":2},{"value":"Pinning within a major (optional)","id":"pinning-within-a-major-optional","depth":2},{"value":"Lifecycle signals","id":"lifecycle-signals","depth":2},{"value":"Deprecation banner","id":"deprecation-banner","depth":3},{"value":"Wire signals","id":"wire-signals","depth":3},{"value":"Lifecycle extensions","id":"lifecycle-extensions","depth":2}],"frontmatter":{"seo":{"title":"Versioning & lifecycle"}},"lastModified":"2026-08-19T12:45:50.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/guides/versioning","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}