API versioning, deprecation, and rate limits
This policy defines the compatibility signals an automated client can rely on when integrating with the public trAIce REST API.
URL versioning and compatibility
Public REST operations are versioned in the URL under /api/v1. We may add optional response fields, new operations, and new enum values within a version. A change that removes a field, changes its type, or makes a previously optional request field mandatory requires a new URL version.
Deprecation and sunset signals
When an operation is deprecated, its documentation names the replacement and responses carry a standards-based Deprecation header plus a link to this policy with rel="deprecation". A Sunset header appears only after a retirement date is scheduled. We target at least 180 days between a public deprecation announcement and removal unless a security or legal issue requires faster action.
Rate-limit responses
Limited REST and MCP responses advertise the current IETF draft fields RateLimit and RateLimit-Policy. They also include RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset for compatibility. Reset values are delays in seconds. A 429 response also includes Retry-After, which clients should honor before retrying.
Typed errors
JSON errors include a machine-readable error code, a human-readable message, and a resolution hint. The OpenAPI document references this schema for every documented 4xx and 5xx response.