Compatibility and versioning

The DUST API is versioned in the path — every endpoint lives under /api/v1. Within a version, we evolve the API continuously, but along strict rules: changes are additive by default, anything that would break a well-behaved integration goes through a deprecation window first, and the published OpenAPI specification is the authoritative statement of the contract at any moment.

This page defines what “well-behaved” means for your integration and what we promise in return.

What may change without notice

These changes are considered backward compatible. They can appear in any release, and your integration must tolerate them:

New endpoints and new operations on existing paths.
New optional request parameters, headers, and body fields. Existing requests keep working unchanged.
New fields in responses. Objects grow over time.
New values in enumerated fields — new event types, states, and kinds are added as the product grows.
New error codes for failure modes that previously surfaced as a generic code.
Documentation, error message text, and field ordering. Human-readable strings are not contract; JSON member order is never significant.

Writing an integration that stays compatible

The rules above are safe if your client follows standard tolerant-reader practice:

Ignore response fields you don’t recognize. Never fail on unexpected members, and don’t use strict schema validation that rejects unknown fields.
Tolerate unknown enum values. Branch on the values you handle and fall through cleanly on ones you don’t.
Branch on error code, never on message. Codes are stable identifiers; messages are localized and can be reworded. See Request conventions.
Treat IDs and pagination cursors as opaque strings. Persist and replay them; never parse or construct them.
Call only what the published specification documents. Endpoints, fields, and behaviors not in the public OpenAPI spec carry no compatibility promise.

An integration that follows these rules is unaffected by additive change and is what the promises below protect.

What we treat as breaking

We do not do any of the following to a published /api/v1 operation without the deprecation process described below:

Removing or renaming an endpoint, request parameter, or response field.
Changing a field’s type or format.
Making an optional request input required, or narrowing the values an input accepts.
Removing a value from an enumerated field.
Changing the error code or HTTP status returned for an existing, documented failure mode.
Requiring a higher authorization tier or new permission for an existing operation.
Materially changing an operation’s semantics, even if its shape is unchanged.

Deprecation

When we do need to retire or reshape something, it is deprecated first:

The operation or field is marked deprecated: true in the published OpenAPI specification, and the deprecation is noted in these docs.
Deprecated functionality keeps working, unchanged, for at least 90 days from the announcement.
A documented replacement is available before or at the moment of deprecation whenever one exists.

Versioning

New major versions are rare by design. /api/v1 evolves additively; we would introduce a /api/v2 only for a reshape that cannot be expressed compatibly, and /api/v1 would then remain supported through a long, explicitly announced migration period — never removed on the deprecation window above.