---
title: "Speko API versioning and deprecation policy"
description: "Speko REST API versioning, backward-compatibility, deprecation, sunset, migration, and rate-limit conventions for durable agent integrations."
canonical: "https://speko.ai/developers/versioning"
last-updated: "2026-08-24"
---

> ## Speko page index
> The complete index of every page on this site is at: https://speko.ai/llms.txt
> Read it before exploring further. It lists the exact Markdown URL for every canonical HTML page.

# API versioning and deprecation

Developers

Speko REST API versioning, backward-compatibility, deprecation, sunset, migration, and rate-limit conventions for durable agent integrations.

## Stable major versions

Speko's stable REST operations use a major version in the URL, beginning with `/v1`. Backward-compatible fields, enum values, and endpoints may be added within v1. A change that removes a field, changes its meaning, or makes a previously valid request invalid requires a new major path. The[OpenAPI 3.1 contract](https://relay.speko.dev/openapi.json) is the language-neutral source for current request and response shapes.

## Deprecation and sunset signals

No v1 operation is currently deprecated. Before Speko removes a stable operation, the response will carry the RFC 9745`Deprecation` header and a `Link` with the`deprecation` relation to its migration instructions. A dated `Sunset` header will be announced at least 90 days before shutdown. The same change appears in the[dated public changelog](https://speko.ai/changelog), JSON Feed, and RSS feed with an effective date, sunset date, and concrete migration action.

- **Compatible change.** Continue using v1; tolerate unknown response fields and enum values where the contract allows them.
- **Deprecated operation.** Follow the linked migration and move before the advertised Sunset date.
- **Model identifiers.** A renamed model keeps an input alias; catalog and response headers publish the canonical identifier.

## Errors and request quotas

Router errors use a JSON `error` object with stable`code`, `message`, `hint`, and`retryable` fields. Every public Router response advertises the default edge quota as`RateLimit-Policy: "relay-ip";q=2000;w=300`: 2,000 requests per five-minute window for each public source IP. Organization and provider concurrency controls can impose a lower effective limit. An application-generated 429 also includes`Retry-After`; agents must wait at least that long and then continue with exponential backoff rather than retrying in a tight loop.