Versioning and compatibility¶

A script that worked last month should work this month. This page says what /api/v1/ promises not to change under you, and what it deliberately leaves free.

The promise, from launch day¶

Within v1, we only add. New endpoints, new optional request fields, new response fields and new values in open enums can arrive at any time, without notice.

We don't take away. For the life of v1, no endpoint or response field is removed, nothing is renamed, and no optional request field becomes required. Changes like that wait for v2.

At least 90 days' notice. If something in v1 ever has to be retired, every team with an active API key is told by email at least 90 days before it stops working, and the change is noted here and in the release notes.

v2 doesn't switch v1 off. When v2 ships, v1 keeps working. Retiring v1 itself also gets at least 90 days' notice, counted from the day v2 is generally available.

What isn't covered¶

Depend on these and you're depending on something we never promised:

• Wording. Status codes and error.code values are covered. The human-readable message isn't.
• Order. Lists have no guaranteed order.
• Timing. How long a job takes, and how soon a poll reflects a change.
• New values. A new job status or analysis_type can appear. Treat unknown values as "not for me", not as errors.
• Routing details. Where a job ran beyond its compute tier isn't part of the API. solver_wall_time_seconds is always null. The compute tier the job ran on (selected_compute_tier) is covered, and so is the field compute_hardware, though the hardware names it reports may change.
• Anything undocumented. If the OpenAPI schema doesn't describe it, it isn't promised, even if it works today.

Two exceptions apply even after launch. A field that leaks data it shouldn't is fixed immediately, with notice afterwards. And when behaviour plainly contradicts this documentation, fixing it is a bug fix, not a breaking change, though it will still appear in the release notes.

Results and solvers¶

The API's shape is versioned as above. The science is versioned separately:

• Each analysis has a contract_version, returned by /analysis-types/. It changes when an analysis's inputs or outputs change meaning.
• Each job records the solver build that ran it, solver_version, worker_image_tag, worker_image_digest and worker_application_revision, and the hardware it ran on, compute_hardware. A solver upgrade can shift results in the last digits. Keep these fields alongside your numbers if you need to reproduce or audit them later.

Writing a robust client¶

• Ignore response fields you don't recognise.
• Don't fail on unknown enum values.
• Read choices (backends, tiers, parameters) from /analysis-types/ rather than hard-coding them.
• Send Idempotency-Key on every submission.