export const metadata = {
  title: "Versioning",
  description:
    "How the FaithTranscripts API evolves, our compatibility guarantees, and deprecation policy.",
  alternates: { canonical: "/docs/api/versioning" },
};

# Versioning

## Path versioning

Every endpoint is prefixed with a version: `/api/v1/...`. Today, that
version is `v1`. We commit to **best-effort** backward compatibility
within `v1` — we'll avoid breaking changes when we can and announce
anything we do change in the [changelog](/docs/api/changelog).

Major breaking redesigns would ship behind `/api/v2/...` if they ever
happen. `v1` would keep running for a reasonable transition period.

<Callout variant="info">
  **Best-effort policy.** We're not committing to a formal deprecation
  window at launch. Breaking changes are discouraged but not formally
  forbidden. When one is needed, the changelog entry calls it out
  prominently at the top of the page.
</Callout>

## What counts as a breaking change

Treat as **breaking**:

- Removing an endpoint or making it return a different shape.
- Removing or renaming a response field you relied on.
- Tightening validation so a previously accepted request is now rejected.
- Changing the meaning of an existing field.

Treat as **non-breaking** (safe to roll out within `v1`):

- Adding new endpoints.
- Adding new fields to response bodies.
- Adding new optional request fields (with sane defaults).
- Adding new error types (you should treat unknown error types as
  `server_error`).
- Adding new event types or webhook payload fields.

## What you should do

1. Ignore unknown fields in responses. Tomorrow's API will send more than today's.
2. Fail closed on unknown error types — log and treat as a retryable server error.
3. Watch the [changelog](/docs/api/changelog) before upgrading integrations.
4. Use the `object` field on responses (e.g. `"object": "transcript"`) to discriminate if you ever parse across resource types.

## Future: sandbox

No sandbox environment in v1. Customers integrate against production
from day one. Usage is tracked in our internal ledger so we can see real
behavior and decide later whether a sandbox is worth building.