OpenRath v2 API and Maintenance Policy#

This policy is part of the Stable v2.0.0 release. It defines public contract classifications, compatibility expectations, and the maintenance process.

Stability levels#

  • Stable: documented public Python symbols, persisted v2 schemas, stable error codes, and migration CLI. Breaking changes require a new major version.

  • Preview: explicitly labelled new API, deployment-helper, or adapter SDK surfaces. Changes are documented with release notes and migration guidance.

  • Experimental: explicitly labelled research integrations and extension hooks. They may change in a minor release and must not be required for the durable Run, security, or storage contracts.

  • Public v2 additions carry an explicit classification in release notes or this policy. Internal modules and names beginning with _ remain internal.

The Agent Server OpenAPI document is the contract source for /v1 operations and records each operation’s stability classification.

OpenRath v2.0.0 itself is a Stable release. Per-surface classifications describe compatibility commitments for individual APIs; they do not change the release status of v2.0.0.

For 2.0.0, the Python v1 façade remains supported and the Agent Server follows the compatibility process defined here.

Action and object authorization#

Authentication alone grants no access. Tokens carry explicit action grants; * is an intentionally privileged reference-only grant. The service enforces the following minimum actions:

Resource

Read

Mutate or control

Assistant

assistant.read

assistant.create

Session

session.read

session.create

Run

run.read

run.create, run.cancel, run.resume

Interrupt

interrupt.read

interrupt.decide

Feedback

—

feedback.create

Memory

memory.search

memory.put, memory.delete

Metrics

metrics.read

—

Run, Session, Interrupt, Feedback, and Memory operations also verify tenant and project scope. A user-scoped memory namespace cannot name another principal unless the token has memory.admin. Cross-scope objects are returned as not found to avoid disclosing their existence. Control-plane mutations emit redacted security audit events when an AuditSink is configured.

SemVer and deprecation#

  • Patch releases contain compatible fixes, security updates, and documentation.

  • Minor releases may add compatible functionality.

  • Breaking Stable API or persisted-schema changes require a new major release.

  • Stable APIs are deprecated before removal. The default notice is two minor releases and at least six months, unless retaining the API would preserve an actively exploitable vulnerability.

  • Database migrations are forward-only and additive during the rollback window. Application rollback precedes removal of old columns or tables.

v1 compatibility#

The v1 Python façade remains available through its published maintenance window. v1 JSONL Sessions import as non-resumable historical evidence because they do not contain a durable program counter or effect outcome. Maintenance updates and timelines are published through release notes.

Security reporting#

Report suspected vulnerabilities privately through the repository’s GitHub Security Advisory flow. Do not open a public issue with exploit details, credentials, tenant data, or unredacted traces. Maintainers should acknowledge, triage severity, coordinate a fix and advisory, and publish remediation and affected-version information. Secrets found in reports must be rotated rather than copied into tests or logs.

Release integrity#

Releases publish compatibility and migration notes, reproducible image digests, dependency locks, a CycloneDX SBOM, security scans, and benchmark profiles. Tag and artifact publication remain explicit repository-owner actions.

Source: tagged API governance document.