Changelog

Newest first. Each entry names the API version it applies to. You pin a version with the BetterJobs-Version header. See Versioning.

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 (sync, up to 100 per page, dry_run estimate), GET /jobs/{id}
Async searches	POST /searches (up to 10,000 jobs), GET /searches/{id}
Companies	GET /companies/{domain} with is_hiring and hiring_pulse
Watches and events	POST /watches, GET /watches, DELETE /watches/{id}, GET /events, POST /webhooks/replay
Account and billing	GET /account, GET /billing/ledger
Providers	GET /providers with live status
Sandbox	POST /sandbox/jobs/search, 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.
• Canonical jobs with sources[] provenance, p_real, lifecycle fields and license. See Canonical jobs.
• 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.
• Partial results: a failed or slow provider gives 200 with metadata.status: partial, never an error.
• Webhooks: event types 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.

Docs and machine-readable files

• OpenAPI 3.1 spec at /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.
• MCP server for agents. See MCP server.

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.