---
title: "OrchestKit API versioning, deprecation & sunset policy"
description: "The OrchestKit docs API is public, read-only, and free. This page states how it is versioned, how deprecations are announced, and what guarantees integrations can rely on."
canonical: "https://orchestkit.yonyon.ai/api-policy"
---

# OrchestKit API versioning, deprecation & sunset policy

> The OrchestKit docs API is public, read-only, and free. This page states how it is versioned, how deprecations are announced, and what guarantees integrations can rely on.

## Versioning

- The current API is **v1**, reachable both unversioned (`https://orchestkit.yonyon.ai/api/*`) and under the path-versioned alias (`https://orchestkit.yonyon.ai/api/v1/*`).
- The unversioned path always tracks the latest version; pin `/api/v1/*` if you want path stability.
- **Breaking changes never ship in place.** They ship under a new `/api/vN` prefix; existing prefixes keep their behavior.
- Additive changes (new endpoints, new optional fields) ship continuously without a version bump.

## Deprecation

Nothing is deprecated today. When an endpoint is deprecated:

- Its responses carry the RFC 8594 `Deprecation` header from the day of announcement.
- A `Sunset` header states the date after which the endpoint may stop responding, **at least 6 months** after the deprecation announcement.
- A `Link` header with `rel="deprecation"` points at migration notes.
- The deprecation is listed in the [changelog](https://orchestkit.yonyon.ai/changelog) and on this page.

## Sunset guarantees

- Deprecated endpoints keep working until the `Sunset` date.
- After sunset, calls return `410 Gone` with an RFC 9457 problem body linking the replacement.

## Rate limits

Every API response carries the IETF `RateLimit-*` headers so a client can pace itself without probing for the ceiling.

- `RateLimit-Policy`, `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` on every response (legacy `X-RateLimit-*` twins included).
- Exceeding the window returns `429` with `Retry-After` and an RFC 9457 problem body.
- Limits are per IP, per endpoint, over a fixed 60-second window.

## Webhooks

OrchestKit **does not emit webhooks**, the API is read-only and request/response only, so there is no webhook registration, no event delivery, and consequently no webhook signing scheme. (Mentions of "webhooks" elsewhere in the docs refer to skill/agent content that helps you build webhooks in *your* applications.)

## Stability of machine-readable surfaces

- [OpenAPI spec](https://orchestkit.yonyon.ai/api/openapi), regenerated every release; schema-compatible within a major version.
- [MCP server](https://orchestkit.yonyon.ai/api/mcp), tool names and shapes follow the same deprecation policy as REST endpoints.
- [llms.txt](https://orchestkit.yonyon.ai/llms.txt) · [API catalog](https://orchestkit.yonyon.ai/.well-known/api-catalog) · [auth policy](https://orchestkit.yonyon.ai/auth.md)