> For the complete documentation index, see [llms.txt](https://herd-security.gitbook.io/herd-security-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://herd-security.gitbook.io/herd-security-docs/api-documentation/versioning-and-stability.md). # Versioning & Stability Versioning, stability, and deprecation policy for the Herd Security public API. ## Versioning The API is versioned in the URL path. The current and only version is `v1`: ``` https://api.herdsecurity.io/api/v1 ``` ## Stable endpoints All ten `/api/v1` endpoints in the [Endpoint Reference](/herd-security-docs/api-documentation/endpoint-reference.md) are treated as **stable and contractual**: users, trainings, tracks, tags, tag trainings, enrollments, audit logs, and the three compliance evidence feeds. The [MCP server](/herd-security-docs/api-documentation/mcp-server.md) is a separate surface. Its tool catalog mirrors HerdAI's tools and grows with them; write clients that tolerate new tools appearing in `tools/list`. ## Change policy * **Additive changes ship without notice.** New endpoints, new optional query parameters, new response fields, and new enum values (for example, new compliance frameworks) may appear at any time. Write clients that ignore unknown fields and tolerate unknown enum values. * **Breaking changes ship as a new version path** (for example, `/api/v2`) — never in place. Removing or renaming a field, changing a field's type or meaning, or removing an endpoint qualifies as breaking. * **Deprecation window.** When a new version replaces an old one, the old version keeps working for a published deprecation window before shutdown, announced in advance to API key holders. ## API keys and scopes API keys currently grant read access to the entire `/api/v1` surface for your organization at [1,000 requests per minute per key](/herd-security-docs/api-documentation/rate-limits.md). Per-key scopes (for example, an evidence-only key) and differentiated partner rate limits may be introduced later; if they are, existing keys will keep their current access. Questions about the stability contract? Contact .