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

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

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

// 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, 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.

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.
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 or a bj_test_ key, then deploy.

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

Related

• Changelog
• OpenAPI and SDKs
• Authentication