Job Opportunities API

Check the data. Then trust it.
Sign inGet a free key

Documentation

Everything, in one place

The Job Opportunities API, the ledger behind it, and every control on this website, documented to the level of individual parameters and individual buttons. Each concept is one sentence you can read at a glance, with the reasoning and the exact contract one click away.

37 pages164 documented concepts2,437,027 live listings237 countries

Figures above are read from /public/coverage (measured 27 October 2026, 04:52 UTC). Nothing on this site quotes a number it did not fetch.

Quickstart: first call in a minute →Parameter referenceFor a program: /docs/ai/index.md

I am integrating today

  1. Quickstart: keyless call, then a key, then an authenticated one.
  2. Authentication: one header, three accepted spellings.
  3. Pagination, and the one rule that bites.
  4. Errors: which to retry and which not to.
  5. Parameters: generated from the live spec.

Everything on this site

Start here

First call, conventions, and how to read this site.

OverviewWhat the Job Opportunities API is, what it deliberately is not, and the ten minutes of reading that will save you the most time.4 sections · What the Job Opportunities API is · What it is not · Every endpoint, in one table · …QuickstartFrom nothing to a real response in one command, and to an authenticated one in about a minute. No card at any point.4 sections · Step one: a real response, with no account (statistics) · Step two: get a key · Step three: your first authenticated call · …If you are a programThis documentation has a plain-Markdown mirror with no JavaScript, no redirects and no browser required. Here is where it is and what is in it.4 sections · The machine-readable mirror · What is in the mirror · The rules that matter most to a program · …MCP serverA remote MCP server at api.jobopportunitiesapi.org/mcp (Streamable HTTP), so an AI agent in Claude, Cursor, Windsurf, VS Code or Cline can search live job postings with the same key, metering and plan limits as the REST API.5 sections · What this is · The six tools · Client configuration · …How to read this siteThree tiers on every concept, a copyable link on every section, and a rule about numbers that explains why almost nothing here is typed by hand.4 sections · The three tiers · Linking to one section · Why almost no number on this site is typed by hand · …Beta & coming soonWhat is live today, labelled BETA and openly partial, and what is still being built. Nothing on this page is a promise of a ship date.1 section · What BETA means on this site

The ledger

What the data is, where it comes from, and what it is not.

What the ledger isEmployer-direct openings, kept as a record rather than a feed. What that phrase actually commits us to, and who it suits.3 sections · “Employer-direct”: what it means and what it excludes · A ledger, not a feed · Who this suits, and who it does notThe data modellive + withheld + closed = ledger_rows, and it reconciles exactly. Almost every misunderstanding about this product traces back to this one equation.5 sections · The three populations · Withheld rows: held, not served · Closed roles · …ProvenanceEvery field on every row says whether the source published it, whether we inferred it, or whether it is absent. This is the most distinctive thing in the product.4 sections · field_sources: per-field provenance · require_fields: the honest subset · Why require_fields=category is an error · …Sourcing and refusalsThe three source classes, the providers inside each, the redistribution flag that gates them, and the sources we fetch for ourselves and never republish.5 sections · The three source classes · Every provider, with its live row count · The redistribution flag: a join, not a filter · …Coverage and honestyHow to read /public/coverage, why the weak numbers are published as prominently as the strong ones, and what measured_at and stale actually mean.6 sections · The coverage report · Per-field completeness · Per-country coverage · …Employer opt-out and takedownsHow a site owner removes themselves, why the removal is verified rather than taken on trust, and how it propagates to every endpoint.3 sections · Removing your site · How it propagates · Corrections and takedowns for a single listing

API

Hosts, auth, limits, paging, errors, and every parameter.

API overviewHosts, versioning, caching, CORS and the HTTP conventions every endpoint follows. Read the hosts section first: getting it wrong costs people hours.5 sections · Two hosts, and which one to send requests to · Versioning and how changes are made · CORS and calling from a browser · …AuthenticationOne header, three accepted spellings, and a deliberate refusal to tell an attacker which kind of wrong a wrong key is.4 sections · The header · Three accepted spellings, and why · What a rejected key looks like · …Keyless accessWhat /public/* gives you with no account: real aggregate numbers against the live ledger (coverage, facets, freshness, providers, the price list, the spec). Job and company ROWS are not part of that anymore: they need a free key, full stop.3 sections · What you get without an account · The limits, exactly · Getting the rows the statistics describeRate limitsTwo independent ceilings (requests per minute and per day) plus a monthly record allowance that is a licence rather than a throttle. They fail differently.4 sections · The per-plan limits · The response headers · Backing off correctly · …PaginationKeyset cursors, not offsets. One rule matters more than the rest: hand next_cursor back exactly as you received it.5 sections · How paging works · How many rows match: include_total · next_cursor is opaque: this is the rule that bites · …ErrorsEvery status the API emits, its JSON shape, whether it is worth retrying, and what to do about it. Two of them are routinely confused and it is expensive.5 sections · The shape of an error · Every status code · 402: the licence, not the throttle · …ParametersEvery query parameter the listing endpoints take, grouped by what it does, generated from the live specification so it cannot drift.13 sections · How to read these tables · Paging · Place: country, city, state · …FieldsEvery field on a job row and a company row, with its type, whether it is always present, and whether it can ever be our inference rather than the source's statement.5 sections · The job row · field_sources · The salary fields · …Filtering cookbookHow the filters combine, how to exclude rather than include, which text filter to reach for, and which queries are expensive enough to time out.6 sections · Twenty questions, and the query for each · How filters combine · Excluding rather than including · …

Endpoints

Every route, with its full contract and worked calls.

ListingsThe four endpoints that return job rows: the live list, one listing, the closure list, and the cheap id-only closure feed.4 sections · GET /v1/jobs · GET /v1/jobs/{id} · GET /v1/jobs/closed · …CompaniesThe employer directory, the single-company endpoint, and an honest account of why company slugs are not yet stable.3 sections · GET /v1/companies · GET /v1/companies/{slug} · Company slugs are not yet guaranteed stableThe delta feedOne ordered stream of everything that changed (created, updated, withdrawn and delisted), so you never have to re-read the ledger to find out what moved.3 sections · GET /v1/changes · The four change kinds, and the one that breaks integrations · The sync loop, written correctlyBulk exportThe whole corpus as a stream of NDJSON, resumable to the exact row, with one failure mode you must handle: the error can arrive as the last line of a 200.3 sections · GET /v1/export · Resuming an interrupted export · The failure mode that catches peopleKey and metadataFour endpoints that describe the API rather than return rows: your key, the filter vocabularies, the freshness report and the provider list.4 sections · GET /v1/me · GET /v1/meta/facets · GET /v1/meta/freshness · …Keyless endpointsEverything under /public/*, what each returns, and which of them have no keyed equivalent at all. Four routes used to be in this list and are not anymore: see the table below it.6 sections · The complete list · GET /public/launch-offer · /public/jobs and /public/jobs/{id}: moved behind a key · …

Recipes

Runnable programs for the things people actually build.

Client codeA working client in curl, Python, JavaScript and Go. No SDK, no dependencies, and every request re-sent against the live API before this page ships.4 sections · curl · Python · JavaScript and TypeScript · …Keeping data currentFour jobs you will end up writing: a daily country pull, an incremental sync, closure detection, and a bulk export, with the record cost of each.4 sections · A daily pull for one country · An incremental sync · Detecting closures cheaply · …Things to buildThree complete builds (a job board, an employer watcher, a CRM enrichment job) and an honest list of which integrations exist today.4 sections · A job board · Watching an employer · Hiring signal for a CRM · …

Account & billing

Plans, the record meter, sign-in, invoices.

PlansWhat each plan includes, rendered from the live price list, and what actually distinguishes them, which is records and entitlements, not features.5 sections · The plans · Annual billing · The two entitlements · …The record meterThe licence is on rows delivered, not on requests made. This is the most commonly misunderstood mechanic here, and it changes how you write your client.4 sections · What counts as a record · Records versus requests · Running out · …Sign-in and the dashboardPasswordless sign-in, every control on the account page, and what rotating or cancelling a key actually does.4 sections · Signing in · Every control on the dashboard · Rotating a key · …Billing, invoices and statusWhat happens between clicking buy and the key switching on, where the invoice comes from, and how to tell whether the data behind the API is current.6 sections · Checkout · The launch discount · Partners: Creem affiliate programme · …

The website

Every page, every control, and what each one does.

The ledger browserEvery control on the home page, the job page and the company pages, what each one sends to the API, and what each label on a row actually asserts.4 sections · The home page: the ledger itself · The filter panel, including Allow and Exclude · A job page · …Every page and every formThe complete route list, what the header and footer link to, and every form on the site with the fields it collects and where they go.4 sections · Navigation: the header and the footer · Every route on the site · Every form, and where it posts · …Legal, cookies and crawlersThe legal pages and what each covers, exactly what this site stores in your browser, the AI disclosure, and the crawler policy — including where it differs by bot.4 sections · The legal pages · What this site stores in your browser · The AI disclosure · …

How this site is put together

Three tiers on every concept

One sentence always visible. In depth for why it exists and what people get wrong. Exact contract for types, defaults and errors. Both expand in place, and both are in the served HTML whether you open them or not, so a crawler or an agent reading the raw page receives everything.

How to read this site →

Deep links to any section

Every section has a § button that copies its permanent link, and /docs?s=<section-id> resolves an id to whichever page owns it. Ids are unique across the whole site, and the build fails if two ever collide.

Linking to one section →

No number here is typed by hand

Every figure is rendered from the endpoint that owns it and printed with the instant it was measured. Every parameter and field table is generated from the OpenAPI spec. Every published request is re-sent against the live API before this site is allowed to build.

Why →

A machine-readable copy of all of it

Every page also exists as plain Markdown under /docs/ai/, served as text/markdown, rendered from the same source as the HTML so the two cannot drift.

/docs/ai/index.md →
Documentation · Job Opportunities API