# Changelog

> What changed in the API and the docs, and when?

Source: https://docs.betterjobs.cc/resources/changelog/

Newest first. Each entry names the API version it applies to. You pin a version with the `BetterJobs-Version` header. See [Versioning](https://docs.betterjobs.cc/platform/versioning.md).

## 2026-10-01: v1 preview

**API version `2026-10-01`.** First public version. It is a preview: endpoints and fields may change before general availability.

> Preview
>
> Changes inside a version are additive only, such as new endpoints or new optional fields. Breaking changes ship as a new dated version, listed here. Build your integration to ignore fields it does not know.

### Endpoints

Base URL `https://api.betterjobs.cc/v1`.

| Area                | Endpoints                                                                                                                                                                                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Jobs                | [`POST /jobs/search`](/api/operations/searchjobs/) (sync, up to 100 per page, `dry_run` estimate), [`GET /jobs/{id}`](/api/operations/getjob/)                                                                                                                   |
| Async searches      | [`POST /searches`](/api/operations/createsearch/) (up to 10,000 jobs), [`GET /searches/{id}`](/api/operations/getsearch/)                                                                                                                                        |
| Companies           | [`GET /companies/{domain}`](/api/operations/getcompany/) with `is_hiring` and `hiring_pulse`                                                                                                                                                                     |
| Watches and events  | [`POST /watches`](/api/operations/createwatch/), [`GET /watches`](/api/operations/listwatches/), [`DELETE /watches/{id}`](/api/operations/deletewatch/), [`GET /events`](/api/operations/listevents/), [`POST /webhooks/replay`](/api/operations/replaywebhook/) |
| Account and billing | [`GET /account`](/api/operations/getaccount/), [`GET /billing/ledger`](/api/operations/getledger/)                                                                                                                                                               |
| Providers           | [`GET /providers`](/api/operations/listproviders/) with live status                                                                                                                                                                                              |
| Sandbox             | [`POST /sandbox/jobs/search`](/api/operations/sandboxsearchjobs/), no key, fixed illustrative data                                                                                                                                                               |

### Behavior

- **Waterfall** across six partner providers (Reqbeat, SignalsAPI, TheirStack, JobsPipe, Coresignal, Techmap) and the BetterJobs index. Strategies: `cheapest_first` (default), `freshest_first`, `max_coverage`, `consensus`, `own_only`. Caps: `waterfall.max_credits`, `waterfall.timeout_ms`. See [Waterfall](https://docs.betterjobs.cc/concepts/waterfall.md).
- **Canonical jobs** with `sources[]` provenance, `p_real`, lifecycle fields and `license`. See [Canonical jobs](https://docs.betterjobs.cc/concepts/canonical-jobs.md).
- **Billing**: 1 credit per unique job returned that you have not already paid for. Duplicates, already-paid jobs, empty pages and dry runs are free. Every charge is in the ledger. See [Credits and billing](https://docs.betterjobs.cc/concepts/credits-and-billing.md).
- **Partial results**: a failed or slow provider gives `200` with `metadata.status: partial`, never an error.
- **Webhooks**: [event types](https://docs.betterjobs.cc/data/events.md) `job.opened`, `job.reposted`, `job.closed`, `job.updated`, `company.hiring_started`, `company.hiring_stopped`, `search.completed`. Signed with `BetterJobs-Signature`, retried for 24 hours, replayable.
- **Platform**: `Idempotency-Key` on every authenticated `POST`, `RateLimit-*` headers, `X-Request-Id` on every response, `X-Credits-Charged` and `X-Credits-Remaining` on billable responses.
- **Errors** with stable codes and a `doc_url`. See [Errors](https://docs.betterjobs.cc/platform/errors.md).

### Docs and machine-readable files

- OpenAPI 3.1 spec at [`/openapi.yaml`](/openapi.yaml). It is the source of truth for every path, field and error code.
- Every page is available as Markdown: append `.md` to its URL.
- `llms.txt`, `llms-full.txt` and `llms-small.txt` for agents. See [llms.txt](https://docs.betterjobs.cc/agents/llms-txt.md).
- MCP server for agents. See [MCP server](https://docs.betterjobs.cc/agents/mcp-server.md).

## Not published yet

Measured coverage, fill rates, freshness and uptime figures are published at GA. Until then, each response reports what it actually got: `metadata.field_coverage` and `metadata.providers`.