Versioning

There are two layers, and they do different jobs:

• The /v1 path is the stable major surface. Outside of the preview period it never changes out from under you. Resource shapes, endpoints, and the URL structure all live here.
• The Dib-API-Version header pins dated behavior. Following Stripe's model, you opt into a specific snapshot of behavior by sending a version date. The current version is 2026-06-01.

How to pin a version

curl -H "Authorization: Bearer $DIB_API_KEY" \
     -H "Dib-API-Version: 2026-06-01" \
     https://dib.io/api/v1/inventory

Don't send the header? You'll be auto-pinned to the API version that was current the day your first key was issued. Every response echoes the resolved version back in the Dib-API-Version header.

Discover the surface

Two unauthenticated endpoints let you (or your SDK) browse what's available without reading a single doc:

• GET /api/v1 — the root index: every resource collection, the standard list/query convention, field formats, and links.
• GET /api/v1/_meta — machine-readable metadata: supported versions, the full scope catalog, and the error catalog.

What we consider breaking

• Renaming or removing a field
• Changing a field's type or nullability
• Tightening validation
• Changing pagination semantics

What we don't consider breaking

• Adding new fields
• Adding new endpoints
• Adding new optional query parameters
• Adding new error types (as long as status codes stay the same)

Deprecation policy

Every dated version is supported for at least 12 months after the next version ships. Deprecations are announced in the changelog, in monthly "API Update" emails, and as Deprecation and Sunsetresponse headers for the last 6 months of a version's life.