OrchestKit API versioning, deprecation & sunset policy

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 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, regenerated every release; schema-compatible within a major version.
• MCP server, tool names and shapes follow the same deprecation policy as REST endpoints.
• llms.txt · API catalog · auth policy