# API Versioning

> How SynthBoard versions its REST API: what counts as additive, what counts as breaking, and the deprecation commitment.

**Canonical URL:** https://www.synthboard.ai/docs/versioning
**Markdown source:** https://www.synthboard.ai/docs/versioning.md

The REST API lives under `/api/v1`. The path is the version.

## Additive changes ship without notice

These can appear at any time and are **not** breaking — write clients that tolerate them:

- New endpoints and new optional request parameters.
- New fields in response bodies (parse what you know, ignore the rest).
- New enum values in fields documented as open (e.g. new modes, new artifact shapes).
- New webhook event types — subscriptions only receive events they opted into.
- New error codes (handle unknown codes generically via the HTTP status).

## Breaking changes require a new version

Removing or renaming a field, changing a field's type or meaning, removing an endpoint, tightening validation on existing input, or changing auth semantics — none of that happens inside `v1`. A breaking change ships as a new versioned path.

## Deprecation commitment

- **90-day notice** before any endpoint or version is retired, announced in the [changelog](https://www.synthboard.ai/docs/changelog) and by email to affected API key owners.
- **Sunset header** — when the first deprecation ships, deprecated endpoints will carry an RFC 8594 `Sunset` header with the retirement date. This is a forward commitment: no endpoint has been deprecated to date, so you will not see this header today.
- **Legacy surfaces stay up during their window** — the per-key webhook mechanism (`X-Mcp-Signature`) is already documented as legacy; existing configurations keep working while subscriptions are the recommended path.

## Where to watch

The [changelog](https://www.synthboard.ai/docs/changelog) records every wire-visible change. The OpenAPI document at https://www.synthboard.ai/api/v1/openapi.json carries the current spec version in `info.version`.

## MCP surface stability

The MCP server follows the same philosophy: tool names and argument schemas are contracts. New tools, resources, and prompts are additive; argument-schema changes are deliberate, snapshot-tested events. Clients should list tools at connect time rather than hardcoding the inventory.

## Related

- [Changelog](https://www.synthboard.ai/docs/changelog)
- [API reference](https://www.synthboard.ai/docs/api)
- [Webhooks](https://www.synthboard.ai/docs/webhooks)

## How to cite this page

> SynthBoard API versioning policy — https://www.synthboard.ai/docs/versioning

Site: https://www.synthboard.ai