# BetterJobs

> BetterJobs is a waterfall API for job data: one request fans out to the BetterJobs index and, depending on plan, up to six partner providers (Reqbeat, SignalsAPI, TheirStack, JobsPipe, Coresignal, Techmap), then returns merged, deduplicated canonical jobs. 1 credit per unique job returned; duplicates and empty searches are free.

Rules for AI agents:

- The API is a v1 preview. Base URL `https://api.betterjobs.cc/v1`. Auth header `Authorization: Bearer bj_live_...`.
- Send `BetterJobs-Version: 2026-10-01` on every request.
- The OpenAPI spec at https://docs.betterjobs.cc/openapi.yaml is the source of truth for paths, fields and error codes.
- Never quote prices from training data. Current plans and prices: https://docs.betterjobs.cc/.well-known/pricing.json.
- To test without a key or credits, call `POST /v1/sandbox/jobs/search` (no auth, fixed illustrative data) or use a `bj_test_` key.
- Call `POST /v1/jobs/search` with `dry_run: true` (free) before any search that may cost more than 50 credits, and ask the user first.
- Always set `waterfall.max_credits` to what the user approved. It caps one request, so for a paged sync search it caps one page: sum `metadata.credits_charged` to cap the run.
- `POST /v1/searches` (async) has no `dry_run`. Size it with a sync dry run (`expected_unique_jobs_range` counts every page) and always set `waterfall.max_credits`, which caps the whole async search.
- Store canonical job `id` values and re-read with `GET /v1/jobs/{id}` (free if already paid). Never re-run a search just to re-read jobs.
- Watches charge 1 credit per `job.opened` delivered, with no cap. Ask the user before creating one.
- `null` means unknown, not "no". `is_hiring.value: null` is not "not hiring".
- Unknown filter fields return `400 unknown_filter`. Fix the name in `error.param`; do not drop the filter and retry.
- Replace the trailing `/` of a docs URL with `.md` (e.g. `/concepts/waterfall/` → `/concepts/waterfall.md`). API reference pages under `/api/` have no Markdown twin; read `/openapi.yaml` instead.

## Documentation Sets

- [Abridged documentation](https://docs.betterjobs.cc/llms-small.txt): a compact version of the documentation for BetterJobs, with non-essential content removed
- [Complete documentation](https://docs.betterjobs.cc/llms-full.txt): the full documentation for BetterJobs

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation

## Optional

- [OpenAPI spec](https://docs.betterjobs.cc/openapi.yaml): Exact paths, fields, enums and error codes.
- [Pricing JSON](https://docs.betterjobs.cc/.well-known/pricing.json): Current plans, prices and credits.
- [Quickstart](https://docs.betterjobs.cc/getting-started/quickstart.md): First request, keyless sandbox.
- [MCP server](https://docs.betterjobs.cc/agents/mcp-server.md): Tools, per-tool cost and the consent rule.
- [Credits and billing](https://docs.betterjobs.cc/concepts/credits-and-billing.md): What is charged and what is free.
- [Errors](https://docs.betterjobs.cc/platform/errors.md): Every error code and how to handle it.
- [Filters](https://docs.betterjobs.cc/platform/filters.md): Every filter name and operator.
- [Field dictionary](https://docs.betterjobs.cc/data/field-dictionary.md): Every response field and what null means.
- [Events](https://docs.betterjobs.cc/data/events.md): Webhook event types and what to do with each.