Skip to Content

Versioning and changelog

Versioning policy

The API path is versioned with /v1.

  • Additive changes are allowed within the same version. These are new paths, new fields in responses, new event types, new error codes, and new optional inputs. Clients must ignore or safely handle unknown fields, unknown event types, and unknown error codes.
  • Changes that break required inputs, enum values, or the meaning of a field happen only in a new major version (/v2). We do not make such changes within /v1.
  • When a new major version is released, the end of support for the previous version is announced first.
  • We check that the OpenAPI file and the public examples do not drift from the real service, and if they do, we correct them against the file.

During the Private Beta

The Beta is an exception to the policy above. During the Beta, the contract, limits, and paths may change. Changes are recorded on this page first. Projects in production use should check this page regularly.

End of support notices

  • A path, field, or behavior that will stop being supported is first posted on this page as scheduled for end of support.
  • A notice includes the replacement and the schedule.
  • The goal is that nothing is removed before it is announced, but during the Private Beta a change can happen without notice for security or stability reasons.

Changelog

DateChange
2026-10Added result-check codes (OUTPUT_URL_INVALID, OUTPUT_CONTAINS_CREDENTIALS, INVALID_FILENAME, UNSUPPORTED_FILE_TYPE, and more) and WORKFLOW_UNAVAILABLE to the error table, and documented file retention (24 hours for files uploaded ahead, 30 days for Session files) in limits and data.
2026-10OpenAPI 1.3.0. Added preparations to the GET /v1/usage response. It shows organization work preparation costs apart from execution costs; existing fields (status, total_su, categories, and the rest) keep their meaning. It is null with an execution filter (deployment_id, session_id, turn_id, run_id). A works only key can now add usage:read and still be created without a Deployment. See usage.
2026-10OpenAPI 1.2.0. Added organization works: POST /v1/works, GET /v1/preparations, GET /v1/preparations/{preparation_id}, POST /v1/preparations/{preparation_id}/answers. Added the scopes works:read, works:write, works:approve, works only keys created without a Deployment, and the error codes REVISION_CONFLICT, PREPARATION_IN_PROGRESS, INVALID_TRANSITION, QUESTION_NOT_FOUND, PACKAGE_CHANGED, INVALID_SPEC, INVALID_REQUEST. Requests and responses of existing paths are unchanged. See organization works.
2026-10A Turn that fails because the execution environment preparation step did not finish in time now has error.code SESSION_SANDBOX_UNAVAILABLE, and a Run using that Turn usually has the same code. Before, a Turn showed USAGE_PENDING or EXECUTION_TIMEOUT, and a Run showed USAGE_PENDING or EXTERNAL_EFFECT_UNKNOWN. A Run whose request sent during preparation could not be confirmed is still EXTERNAL_EFFECT_UNKNOWN, and running out of time while waiting for an earlier execution is still EXECUTION_TIMEOUT. Added it to the error table and the next step table.
2026-10Added llms.txt, a summary for AI tools, and a per-code next step table for failed executions. Added six terminal codes that can appear in execution details (EXECUTION_FAILED, CANCELED, AUTHORIZATION_REVOKED, SESSION_DELETED, RUNTIME_CONTEXT_MISMATCH, USAGE_PENDING) to the error table.
2026-10Removed source_agent_id from the GET /v1/deployments and GET /v1/deployments/{deployment_id} responses. Calls use only the Deployment id.
2026-10Private Beta documentation published. Covers Sessions and Turns, Workflows and Runs, events and SSE, webhooks, file input and output, errors, and limits.
Core Concepts