# Job Opportunity Index API

> Every open job and internship we can find — company career sites, their hiring platforms and public employment services in many countries — as a job-posting feed: new, modified and expired postings, counts and employers, with the complete posting text, the exact original URL and rule-derived structured fields (no language model). Documentation files for Large Language Models.

Complete documentation in one file: [https://jobs.centrality.lol/llms-full.txt](https://jobs.centrality.lol/llms-full.txt). OpenAPI specification: [https://jobs.centrality.lol/openapi.json](https://jobs.centrality.lol/openapi.json).

Access: every data endpoint needs `Authorization: Bearer <key>` (a personal key from a subscribed account: https://jobs.centrality.lol/signup, https://jobs.centrality.lol/pricing, https://jobs.centrality.lol/account). Without it the API answers 401, or 402 when the subscription is not active.

## Documentation

- [How the API works](https://jobs.centrality.lol/developer/how-it-works.md): What the feed is and where its postings come from: company career sites, 15+ hiring platforms (Greenhouse, Lever, Ashby, Workday, Oracle, SmartRecruiters, Workable, Recruitee, Personio, BambooHR, Teamtailor, Breezy, ADP, Rippling, Gem) and public employment services (Germany's Federal Employment Agency, EURES for 30 European countries, Switzerland's job-room.ch). How fresh it is, how postings close and change, and that every derived field is read from the posting by rules, with no language model.
- [Your first API call](https://jobs.centrality.lol/developer/your-first-api-call.md): Quickstart: a first GET /api/v1/active-jobs call with time_frame and limit, then filters (title, location, work_arrangement, description_format) in curl and Python.
- [Access, limits and errors](https://jobs.centrality.lol/developer/authentication.md): Every data request needs a personal API key from a subscribed account (/signup, /pricing, /account): Authorization: Bearer joi_... About 1,200 requests a minute per key. Response headers X-Result-Count and X-Last-Id, error codes (400, 401 no/unknown key, 402 subscription not active, 404, 414, 429, 503, 500) and the 25-second query limit.
- [Why this API](https://jobs.centrality.lol/developer/why-this-api.md): What sets the feed apart: no language model (no invented facts), no ingestion delay, public employment services included, complete posting text, exact original URLs, field-level change tracking, staffing agencies labelled, offline English place names, self-hostable, LLM-ready formats.
- [New jobs](https://jobs.centrality.lol/developer/new-jobs.md): GET /api/v1/active-jobs: open postings first indexed within time_frame (1h, 24h, 7d, 6m), newest first. Every parameter (text search, Boolean _advanced expressions, dates, source, employer, agency, experience, work arrangement, employment type, language, education, function, visa, salary, country), offset and cursor pagination, description_format, format (json, jsonl, csv, md), fields, schema=fantastic.
- [Count](https://jobs.centrality.lol/developer/count-endpoints.md): GET /api/v1/active-jobs-count: how many postings the same filters match; time_frame=1m counts everything indexed in 31 days including postings closed since.
- [Modified jobs](https://jobs.centrality.lol/developer/modified-jobs.md): GET /api/v1/modified-jobs: open postings whose title, location, pay, employment type, department or complete text changed upstream in the last 24 hours, with date_modified and modified_fields; date_modified_gte / date_modified_lt windows.
- [Expired jobs](https://jobs.centrality.lol/developer/expired-jobs.md): GET /api/v1/expired-jobs: ids of postings that closed (filled, withdrawn, removed); time_frame 1h, 1d (previous UTC day), 1m, 6m; source filter.
- [Organizations](https://jobs.centrality.lol/developer/organizations.md): GET /api/v1/organizations: every employer with open postings (JSON or CSV) with domain, slug, industry, headquarters, headcount, open and new postings, agency flag.
- [Recommended strategy](https://jobs.centrality.lol/developer/recommended-strategy.md): Keeping a full copy in sync: cursor backfill with time_frame=6m, hourly 1h or daily 24h polling, daily modified-jobs and expired-jobs, outage recovery with date_created_gte, sizing with active-jobs-count.
- [Time fields](https://jobs.centrality.lol/developer/time-fields.md): date_posted (source), date_created (first indexed, monotonic: use for syncs), date_last_seen, date_modified, date_valid_through; all UTC; no delay.
- [Location search](https://jobs.centrality.lol/developer/nuances-of-location-search.md): How location search works: GeoNames-normalised English places as City, Region, Country (UK regions are its countries; city-states without region), raw and normalised names both searchable (Munich finds München), namesakes decided by the posting's country, quoting and OR patterns, the locations_derived family of fields.
- [Advanced searching](https://jobs.centrality.lol/developer/advanced-searching-guide.md): Boolean expressions for title_advanced, description_advanced, location_advanced and organization_advanced: & | ! <-> <N> 'phrase' :* and parentheses, URL-encoding, and the Google-style syntax of the plain parameters.
- [Derived fields](https://jobs.centrality.lol/developer/derived-fields.md): How every derived field is read from the posting by rules: pay, experience, work arrangement, employment type, language, skills, keywords, benefits, responsibilities, requirements, function, visa, agency.
- [Field reference](https://jobs.centrality.lol/developer/field-reference.md): Every field of a posting in active-jobs and modified-jobs, grouped: identity and dates, source, location, pay, the work, content, employer.
- [Supported sources](https://jobs.centrality.lol/developer/supported-sources.md): Every source value for source / exclude_source with its current number of open postings.
- [Country statistics](https://jobs.centrality.lol/developer/country-job-statistics.md): Open postings per country right now, by the job's location.
- [Sample Data](https://jobs.centrality.lol/developer/sample-data.md): Live sample requests for every endpoint and format.
- [Changelog](https://jobs.centrality.lol/developer/changelog.md): What was added, by date.
- [FAQ](https://jobs.centrality.lol/developer/faq.md): Keys, freshness, AI or not, full backfill, drop-in compatibility, country coverage, wrong postings.

## API Reference

- [Active jobs — GET /api/v1/active-jobs](https://jobs.centrality.lol/developer/api/active-jobs.md): Open postings first indexed within the time window, from company career sites, hiring platforms and public employment services, with filtering, full-text search, date ranges, pagination and field selection. Parameters: time_frame, limit, offset, cursor, description_format, include_page_text, format, fields, schema, include_basic_organization_details, include_beta, order_by, include_duplicates, title, description, location, title_advanced, description_advanced, location_advanced, organization_advanced, skill, date_posted_gte, date_posted_lt, date_created_gte, date_created_lt, source, exclude_source, source_type, organization, exclude_organization, domain, exclude_domain, organization_agency, organization_industry, organization_size, organization_headcount_gte, organization_headcount_lt, company_country, experience_level, work_arrangement, employment_type, language, education, taxonomies, exclude_taxonomies, visa_sponsorship, seniority, has_salary, salary_min, currency, country, has_no_location, full_text_only, id, no_collect.
- [Modified jobs — GET /api/v1/modified-jobs](https://jobs.centrality.lol/developer/api/modified-jobs.md): Open postings whose title, location, pay, employment type, department or complete text changed upstream in the last 24 hours, with date_modified and modified_fields on every row. Parameters: limit, offset, cursor, description_format, include_page_text, format, fields, schema, include_basic_organization_details, include_beta, order_by, include_duplicates, title, description, location, title_advanced, description_advanced, location_advanced, organization_advanced, skill, date_posted_gte, date_posted_lt, date_created_gte, date_created_lt, date_modified_gte, date_modified_lt, source, exclude_source, source_type, organization, exclude_organization, domain, exclude_domain, organization_agency, organization_industry, organization_size, organization_headcount_gte, organization_headcount_lt, company_country, experience_level, work_arrangement, employment_type, language, education, taxonomies, exclude_taxonomies, visa_sponsorship, seniority, has_salary, salary_min, currency, country, has_no_location, full_text_only, id.
- [Expired jobs — GET /api/v1/expired-jobs](https://jobs.centrality.lol/developer/api/expired-jobs.md): Ids of postings that closed: filled, withdrawn or removed by their source. Parameters: source, time_frame.
- [Organization list — GET /api/v1/organizations](https://jobs.centrality.lol/developer/api/organizations.md): Every employer with open postings, the largest first, as JSON or CSV. Parameters: format.
- [Search, scraping if needed — GET /api/v1/search](https://jobs.centrality.lol/developer/api/search.md): One call for 'give me this': answers from the index when it holds at least min_results postings; otherwise it launches scraping for exactly this (the title / place / country through the public employment services, a company's career site with company_url) and answers with what exists now plus the request ids, or, with wait=N, waits for the scraping and answers with the fresh postings. Accepts every active-jobs filter. Parameters: limit, offset, cursor, description_format, include_page_text, format, fields, schema, include_basic_organization_details, include_beta, order_by, include_duplicates, title, description, location, title_advanced, description_advanced, location_advanced, organization_advanced, skill, date_posted_gte, date_posted_lt, date_created_gte, date_created_lt, exclude_source, source_type, organization, exclude_organization, domain, exclude_domain, organization_agency, organization_industry, organization_size, organization_headcount_gte, organization_headcount_lt, company_country, experience_level, work_arrangement, employment_type, language, education, taxonomies, exclude_taxonomies, visa_sponsorship, seniority, has_salary, salary_min, currency, country, has_no_location, full_text_only, id, mode, min_results, wait, company_url, refresh.
- [Collect now — GET /api/v1/collect](https://jobs.centrality.lol/developer/api/collect.md): Ask the index to go and get postings for something specific now (a job, a city, a country), above all for a place it has little on: it finds the employers located there (organisations headquartered nearby on Wikidata, offices, companies, hospitals, universities and banks on OpenStreetMap, with their websites), adds the new ones, reads the career sites of the 80 most important at once, searches the public employment services with those words and that place, and moves the place's other companies to the front of the scraping queue. Returns a request id; GET /api/v1/collect/{id} shows progress and what was found. A feed search returning fewer than 20 postings triggers the same automatically. Parameters: title, location, country.
- [Active jobs count — GET /api/v1/active-jobs-count](https://jobs.centrality.lol/developer/api/active-jobs-count.md): How many postings active-jobs would return for the same filters. Parameters: time_frame, include_duplicates, title, description, location, title_advanced, description_advanced, location_advanced, organization_advanced, skill, date_posted_gte, date_posted_lt, date_created_gte, date_created_lt, source, exclude_source, source_type, organization, exclude_organization, domain, exclude_domain, organization_agency, organization_industry, organization_size, organization_headcount_gte, organization_headcount_lt, company_country, experience_level, work_arrangement, employment_type, language, education, taxonomies, exclude_taxonomies, visa_sponsorship, seniority, has_salary, salary_min, currency, country, has_no_location, full_text_only.

## Other endpoints

- `GET /api/jobs`, `GET /api/jobs.md`: the website's search (see [https://jobs.centrality.lol/docs](https://jobs.centrality.lol/docs)).
- `GET /api/job/{id}` and `/api/job/{id}.md`: one posting, every field and its full text.
- `GET /api/company/{slug}`: an employer's profile and hiring insights.
- `GET /api/live`: live system statistics.
- `GET /api/role`: which machine is serving.