API versioning — date-based version tags, stability levels and the guarantees we offer.

• STABLE Production-grade. Backward-compatible changes only — new fields can be added, existing fields will not be removed or repurposed. Safe to depend on for production code.
• BETA Functional, but the response shape may change before STABLE. We try to minimize churn but make no contract. Pin your client to a specific version date if you depend on a BETA endpoint.
• DEPRECATED Scheduled for removal. The endpoint still works for a documented sunset window (typically 6–12 months). Migration path published in the response headers and on this page.
• EXPERIMENTAL Used internally for prototypes. Hidden from the public docs. If you stumble on one in network logs, do not depend on it — it can disappear at any time.

Each endpoint carries a date tag like `v2026-05-15` representing the date of its most recent breaking-change revision. Two things to know:

• Per-endpoint, not per-API /domain/lookup might be v2026-05-15 while /security/ssl-info is v2025-11-02. Endpoints version independently.
• Default = latest STABLE Calls without an explicit version header always get the latest STABLE version of the endpoint. Most integrations want this.
• Pinning available on Pro+ Pass `X-DS-Version: 2025-11-02` to lock a request to a specific revision. Useful when you've certified your client against a particular shape.
• Sunset windows When a new revision lands, the previous one becomes DEPRECATED and is supported for 6–12 months before removal.

We follow conventional definitions. These are the breaking changes that bump an endpoint's version date:

• Removing a field Once shipped on STABLE, fields can only be removed via DEPRECATED transition.
• Renaming a field Treated as remove + add. Old name remains for the deprecation window.
• Changing a field's type string → object, number → string — anything that breaks client parsers.
• Tightening validation Adding new required params or stricter input formats. Loosening (more permissive) is non-breaking.
• Changing error semantics Repurposing an existing error code (e.g. swapping 404 for 410). New codes can be added freely.

These are explicitly allowed within a STABLE version and won't bump the date tag:

• Adding new fields Forwards-compatible. Your client must ignore unknown fields — never break on them.
• Adding new optional params Existing calls behave identically when the new param is omitted.
• Adding new error codes Match on the code field, not on the full set of codes. New codes get added as new failure modes are documented.
• Performance improvements Cache freshness, response time, edge POP changes. You should observe these as faster responses, not different ones.
• New endpoints New URLs under `/api/v1/`. Don't affect existing endpoints.

When an endpoint is deprecated, all responses include a `Sunset:` header and an `X-DS-Successor:` header pointing at the replacement. Four-step migration playbook:

• 1. Identify usage From the dashboard usage page, filter by endpoint to find all keys/services calling the deprecated route.
• 2. Read the migration note Each deprecation is announced on /blog with a side-by-side mapping from old to new response shape.
• 3. Branch + ship Implement the new endpoint behind a feature flag. Run both endpoints in parallel; compare results. Cut over when confident.
• 4. Remove the old path Delete the deprecated client code well before the published sunset date. The dashboard shows last-used-on-deprecated to spot stragglers.