# Versioning

> How does date-pinned versioning work, and what can change within a version?

Source: https://docs.betterjobs.cc/platform/versioning/

The BetterJobs API is versioned by date. You pin a version with the `BetterJobs-Version` header. Within a version, changes are additive only, so code that works today keeps working. The current version is `2026-10-01`.

## Send the header

Send `BetterJobs-Version` on every request.

**curl**

```bash
curl -i https://api.betterjobs.cc/v1/account \
  -H "Authorization: Bearer $BETTERJOBS_API_KEY" \
  -H "BetterJobs-Version: 2026-10-01"
```

**Python**

```python
import os
import requests


session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {os.environ['BETTERJOBS_API_KEY']}",
    "BetterJobs-Version": "2026-10-01",  # pin it in one place
})
resp = session.get("https://api.betterjobs.cc/v1/account", timeout=30)
```

**TypeScript**

```ts
// Pin it in one place and reuse these headers everywhere.
export const BETTERJOBS_HEADERS = {
  Authorization: `Bearer ${process.env.BETTERJOBS_API_KEY}`,
  "BetterJobs-Version": "2026-10-01",
};


const res = await fetch("https://api.betterjobs.cc/v1/account", { headers: BETTERJOBS_HEADERS });
```

If you leave the header out, the request is served with your account’s pinned version. `POST /v1/jobs/search` responses echo the version that served them in a `BetterJobs-Version` response header.

> Always send it explicitly
>
> Relying on the account default means a change to your account’s pinned version changes what your code receives. An explicit header in your code makes the version visible in code review and keeps every environment on the same contract.

## What can change within a version

Within one version, BetterJobs only **adds**. Additive changes include:

- New endpoints.
- New optional request fields and filters.
- New fields in response objects.

Anything that could break working code needs a new dated version. That covers removing or renaming a field, changing a field’s type or meaning, making an optional field required, and changing a default.

> Write tolerant clients
>
> Additive changes are safe only if your code tolerates them. Ignore response fields you do not recognize. Do not fail validation on extra keys. If you generate a client from the [OpenAPI spec](https://docs.betterjobs.cc/platform/openapi-and-sdks.md), make sure its models do not reject unknown properties.

## v1 preview

The API is a **v1 preview**, not generally available. Endpoints and fields may still change before GA. Changes are listed in the [changelog](https://docs.betterjobs.cc/resources/changelog.md).

The deprecation policy for versions after GA, including how long an old version keeps working, will be published at GA.

## Upgrading to a new version

When a new version ships:

1. Read its entry in the [changelog](https://docs.betterjobs.cc/resources/changelog.md).
2. Update your code for the listed changes.
3. Change the `BetterJobs-Version` value in the one place you pinned it.
4. Test against the [sandbox](https://docs.betterjobs.cc/getting-started/quickstart.md) or a `bj_test_` key, then deploy.

Because the version is a header, you can move one service at a time.

## Related

- [Changelog](https://docs.betterjobs.cc/resources/changelog.md)
- [OpenAPI and SDKs](https://docs.betterjobs.cc/platform/openapi-and-sdks.md)
- [Authentication](https://docs.betterjobs.cc/getting-started/authentication.md)