Skip to main content
The Platform API carries the version in the path. Most endpoints are v1, and some that are still pre-stable are v1beta.

v1 and v1beta

Backward compatibility in v1

On v1 paths, existing clients keep working. The following changes are considered compatible and ship without notice.
  • Adding new fields to responses
  • Adding optional request parameters
  • Adding new endpoints
  • Adding new values to enumerated fields such as model IDs, run statuses, and error code values
Breaking changes are never applied to v1 paths. When needed, they ship under a new version path. Every change is recorded in the Changelog.

Using v1beta

v1beta endpoints are pre-stable. Response fields, request parameters, and paths may change or be removed without notice.
If you depend on a beta endpoint in production, we recommend the following.
  • Keep the call sites in one place. When a path or response changes, there is less to fix.
  • Instead of storing responses as-is, extract only the values you need and store them in your own schema.
  • Subscribe to the Changelog. An RSS feed is available.
When a beta endpoint is promoted to v1, it is announced in the Changelog.

Checking the version of an endpoint

If the request path contains /v1beta/, the endpoint is beta. The actual path is shown at the top of each API Reference page.
Versions are promoted per resource. Even when they handle the same data, endpoints can have different versions, such as answer retrieval (/v1/platform/answers) and source statistics (/v1beta/platform/sources/statistics/domains).

Change-resilient clients

  • Ignore unknown fields. Parsing must not fail when a new field is added to a response. Turn off strict deserialization settings that error on unknown keys.
  • Do not assume a field is always present. A field may be missing from a response depending on whether you requested it with the include parameter and whether data exists.
  • Be ready for unknown values. New values may be added to model IDs, run status, and error code. Add a default branch to your conditionals.
  • Keep the version path in a constant. If you do not hardcode /api/v1/platform throughout your code, a promotion only requires a change in one place.