# 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/docs/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.

## 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)