API Versioning
DarkerDB uses dated wire contracts selected with the X-API-Version request header. The /v2 path is the DarkerDB route namespace, not the response contract version.
Header
| Property | Value |
|---|---|
| Header | X-API-Version |
| Format | YYYY-MM-DD |
| Latest | 2026-08-03 |
| Supported | 2026-08-02, 2026-08-03 |
curl https://api.darkerdb.com/v2/items \
-H "X-API-Key: your-api-key" \
-H "X-API-Version: 2026-08-03"Omitting the header follows the latest contract. That works for a website deployed alongside the API. Released desktop, mobile and third-party clients should pin the contract they support.
Every API response echoes the selected contract in X-API-Version and includes Vary: X-API-Version for safe caching.
Resolution
| Sent | Result |
|---|---|
| Absent or empty | Latest contract |
| Supported date | Requested contract |
| Malformed or unknown date | 400 Bad Request |
| Retired date | 410 Gone |
Supported Contracts
- 2026-08-03 is the latest contract.
- 2026-08-02 preserves the previous login response shape.
DarkerDB data endpoints currently have the same response shape in both contracts. Compatibility remains pinned until a client deliberately upgrades.
Retirement
Retired contracts return 410 Gone with resource:gone. Upgrade the client to a supported contract instead of retrying the request.