# Versioning

> What can change within /v1 and what never will, and how you'll hear about changes.

The API's version is in its URL: `https://api.hirehappy.io/v1`. Within `/v1`, nothing you rely on breaks.

## What never changes within /v1

- Fields are never renamed or removed, and never change type.
- Endpoints are never removed, and never start needing more than they do.
- Error `type` codes keep their meaning.

## What may change

These are additions, and integrations should take them in their stride:

- **New endpoints**, and new optional parameters on existing ones.
- **New fields in responses.** Ignore fields you don't know, rather than failing on them; in particular, don't validate responses against a closed schema.
- **New values in choice fields**, like a new interview `kind` or stage `kind`. Handle values you don't know.
- **New error types**, under the existing status codes.
- **Wording**: `msg` in errors, and descriptions in these docs.

Anything that would break an integration waits for `/v2`. When there is one, `/v1` will keep working long enough for you to move, and we'll write to you about it.

## Hearing about changes

Every change to the API is in the [changelog](https://hirehappy.io/docs/changelog), newest first. The [OpenAPI schema](https://hirehappy.io/docs/openapi.json) always describes the API as it is, so diffing it is a quick way to see what changed.
