---
title: "AgentTwin API versioning and deprecation policy"
description: "How AgentTwin versions its public API and announces breaking changes."
canonical: "https://agenttwin.si/api-policy/"
---

# AgentTwin API versioning and deprecation policy

The public REST API uses `/v1` URL versioning. The [OpenAPI document](/openapi.json) describes the supported public subset; undocumented internal routes are not a stable integration contract. OAuth endpoints use their standards-defined paths and advertise capabilities in authorization-server metadata.

## Compatible changes

Additional optional fields, new endpoints and new error identifiers may be added within v1. Clients should ignore unknown response properties, preserve unknown error identifiers and use declared operation IDs and schemas. Do not infer an operation from prose or invent permissions.

## Breaking changes and retirement

An incompatible public contract change requires a new API version. Before scheduling removal of a public version, publish its replacement, migration instructions and planned retirement date on this page and in [current status](/docs/status/). Once a retirement is actually scheduled, affected responses should carry `Deprecation` (RFC 9745), a `Sunset` HTTP-date (RFC 8594), and a `Link` to migration guidance. No version is currently scheduled for retirement, so those headers are not emitted today. This policy does not promise a fixed minimum support window or a contractual SLA.

## Safe integration

Use scoped project-bound OAuth credentials. Follow the advertised `Location` for asynchronous jobs and `nextCursor` for pagination. Retry reviewed cloud test submissions only with the same `Idempotency-Key` and identical JSON body. Different content under the same key returns 409. Keys are retained with run history for up to 30 days; after retention removal, the same key can create a new run. A run in progress remains an accepted job, not a successful test result.