Skip to content
Context docs

Versioning

The version in the path, and the changes clients should tolerate within it.

Every endpoint is under /api/v1/evals, and v1 is the only version. The API has no version header and no date-based versioning: the path is the version. The OpenAPI file’s info.version is 1.0.0.

These changes can happen within v1, so build clients that tolerate them:

  • New endpoints, new response fields and new optional query parameters. Ignore fields you don’t know.
  • New values in a field whose values are listed, such as a run’s status, and new error code values. Handle an unknown value without failing.
  • New wording in error messages. Branch on the status and code, never on the message.

Each deployment runs its own build, so a field described here can be missing on a deployment that hasn’t been upgraded. The OpenAPI file next to this guide describes the build it was made from, which can be newer or older than yours. Your deployment’s own /api/v1/evals/openapi.json always describes your build; compare against your deployment’s own responses.

The CLI matches the deployment it was installed from. After your deployment is upgraded, re-run the install command from Settings > Terminal to update the CLI.