Versioning and deprecation

The version is in the path: https://api.dhanu.ai/api/pub/v1. There is no version header to send.

What can change without a new version

These are additive and can land in v1 at any time. Write your client so they never break it, ignore fields you do not know, and never enumerate an object’s keys to find the one you want:

• a new endpoint
• a new optional request field
• a new response field
• a new value on an enum documented as open (for example an error code)
• a new error code

What needs a new version

These are breaking and only ever ship as /api/pub/v2:

• removing or renaming a field
• changing a field’s type or format
• tightening validation so a request that used to succeed now fails
• changing a status code
• removing an endpoint

When v2 ships, v1 keeps working unchanged for at least twelve months from the announcement.

How a deprecation announces itself

A deprecated endpoint says so on every response:

Deprecation: @1789603200
Sunset: Fri, 17 Sep 2027 00:00:00 GMT
Link: <https://docs.dhanu.ai/developer/reference/versioning>; rel="deprecation"

• Deprecation is the moment it was deprecated, as a Unix timestamp (RFC 9745).
• Sunset is when it stops working (RFC 8594), never less than a year after Deprecation.
• Link points at the replacement, or at this page.

A deprecated field cannot carry headers, so it is listed on the OpenAPI document under x-dhanu-deprecated-fields on its operation, with the same sunset date and its replacement. Today that list holds one entry: messages on GET /tasks/{taskId}/messages mirrors data until 17 September 2027.

Every deprecation and every v2 change is also written up in the changelog under the API area.

Test keys follow the same contract

A response from a test-mode key has the same shape as a live one, so a client that works in test mode works in production.