{
  "components": {
    "parameters": {
      "AgencyFlag": {
        "description": "Comma-separated (OR, case-insensitive): `direct`, `agency`,\n`umbrella`, or `unknown` (alias `not_stated`). Who the employer of\nrecord is: the advertiser itself, a temporary-work agency (the\nengagement is then `employee`, because EU and national law make agency workers\nemployees of the agency, and `contract_category` describes the\ncontract WITH the agency), or an umbrella / portage company. `unknown`\nselects rows where it is not established.\n",
        "in": "query",
        "name": "agency",
        "schema": {
          "type": "string"
        }
      },
      "Category": {
        "description": "Comma-separated. uncategorised selects rows with no confident classification.",
        "in": "query",
        "name": "category",
        "schema": {
          "type": "string"
        }
      },
      "City": {
        "description": "Comma-separated city names, matched exactly but case-insensitively in\nevery script (`city=αθήνα` finds `Αθήνα`) and, for most cities, without\nregard to accents (`city=Medellin` finds `Medellín`, since 12 Nov 2026). A\ntwo-letter term that is a US state code or a country code (what\n`country=` accepts, plus UK for GB) qualifies the other city terms\ninstead of naming a second city, so `city=Exeter, RI` returns only\nExeter in Rhode Island: the US state reading wins a collision, and a\nqualifier with no city term left (such as `city=GB`) is still matched\nas a city value. A term after the first city that names a Canadian\nprovince, an Australian state, a UK nation or a UK county (`city=London, ON`,\n`city=Victoria, BC`, `city=Exeter, Devon`) narrows the match to that\ncountry and region; a row counts when its region or the words of its\nlocation text carry the qualifier, so a row that states no region is not\nreturned for a regional query. Any other term stays a city, so\n`city=Berlin,Munich` is two cities. Native and transliterated\nspellings of a city are one city (`city=Munich` also finds `München` and\n`Muenchen`; `city=Αθήνα` finds Athens in Greece). For most cities of the\npublished city list (/public/facets) accents are ignored in both\ndirections: a term also finds every stored spelling that differs from it\nonly by accents (Bogota finds Bogotá, Montreal finds Montréal). For the\nlargest cities a term finds only the spellings it found before, so type\nthe accents as the city is stored (São Paulo). Places whose names differ only by accents are\ntherefore one city name (Munster also finds Münster): add `country=` to\nkeep one.\n",
        "in": "query",
        "name": "city",
        "schema": {
          "type": "string"
        }
      },
      "Company": {
        "description": "Comma-separated company slugs.",
        "in": "query",
        "name": "company",
        "schema": {
          "type": "string"
        }
      },
      "CompanyDomain": {
        "description": "Comma-separated bare domains, e.g. `stripe.com,figma.com`: no scheme\nand no path, at most 100 (more is a 422 `too_many_values`, never\ntruncated). The join key you already have in a CRM. 37.2% of\ncompanies carry a domain; the rest can never match this filter.\n",
        "in": "query",
        "name": "company_domain",
        "schema": {
          "type": "string"
        }
      },
      "CompanyNameContains": {
        "description": "Boolean text search on the employer name (2026-11-10), with the same\nsyntax as `title`: `company_name_contains=Siemens | Bosch`,\n`company_name_contains=!(Amazon | Meta)`. Every value is read by the\ngrammar, so a plain `Acme Corp` is both words. Matches the company name\nas the listing carries it; for an exact employer use `company` (slugs).\nThe Fantastic.jobs name `organization_advanced` is accepted as an alias.\n",
        "in": "query",
        "name": "company_name_contains",
        "schema": {
          "type": "string"
        }
      },
      "CompensationType": {
        "description": "Server-side filter for commission-only postings (db/370, DQ rule v5).\nThe only legal value is `commission_only`; any other value is a 422\n`bad_compensation_type` and no records are billed. Informational field\n(see the `compensation_type` description on the Job schema).\n",
        "in": "query",
        "name": "compensation_type",
        "schema": {
          "enum": [
            "commission_only"
          ],
          "type": "string"
        }
      },
      "ContractCategory": {
        "description": "Comma-separated (OR, up to 8, case-insensitive): `permanent`,\n`fixed_term`, `project_based`, `seasonal`, `apprenticeship`,\n`internship`, `other`, or `unknown` (alias `not_stated`). The contract\nKIND the posting states. `contract_category=permanent` returns only\npostings that STATE permanence (CDI, unbefristet, tempo indeterminato,\ncontrato indefinido, ...). A posting that merely says \"Full-time\" is\n`unknown`, because most employers do not state the contract kind and\nthis API does not guess it. The row value is an ARRAY (dual-option\nadverts); the filter matches any element. `other` is a stated form none\nof the named values can represent (zero-hours, casual, per diem,\nMinijob, Werkstudent, ...), never a dumping ground for uncertainty.\n",
        "in": "query",
        "name": "contract_category",
        "schema": {
          "type": "string"
        }
      },
      "Country": {
        "description": "Comma-separated ISO-3166 alpha-2, at most 60 codes (more is a 422 `too_many_values`, never truncated).",
        "in": "query",
        "name": "country",
        "schema": {
          "type": "string"
        }
      },
      "CountryConfidence": {
        "description": "Server-side filter on how trustworthy the job's `country` is (see `field_sources.country`).\n`high` keeps only rows that have a country that is NOT low-trust: `published`, or `inferred`\nby a rule or by gazetteer and language model agreeing (measured precision about 99.5%).\n`low` returns only the `llm_inferred` rows, whose country a language model alone read out of\nthe location text (measured precision about 95%). Omit it to receive everything. Any other\nvalue is a 422 `bad_country_confidence` and no records are billed.\n",
        "in": "query",
        "name": "country_confidence",
        "schema": {
          "enum": [
            "high",
            "low"
          ],
          "type": "string"
        }
      },
      "CountryMatch": {
        "description": "Opt-in, added 8 Nov 2026. Some jobs are open to several countries, for example\n\"Remote (United States | Canada)\". Such a job keeps ONE `country` (or none when no single\ncountry applies) and lists every country it is open to in `countries`.\n`primary` (the default, the same as omitting it): `country`, `exclude_country` and a\nlocked key's country or continent lock compare the job's `country` only, exactly as before.\n`any`: they compare every country in `countries`, so `country=US\u0026country_match=any` also\nreturns a \"Remote (United States | Canada)\" job whose `country` is CA or absent.\nEach job is still one record, whichever of its countries matched. Facets and coverage\ncounts use `country` only. Any other value is a 422 `bad_country_match` and no records\nare billed.\n",
        "in": "query",
        "name": "country_match",
        "schema": {
          "default": "primary",
          "enum": [
            "primary",
            "any"
          ],
          "type": "string"
        }
      },
      "DescriptionContains": {
        "description": "Full-text over the advert body. Only ever matches rows that have one,\nso it implies `has_description=true`.\n\nBoolean syntax, exactly as on `q`: phrases (`\"customer support\"`), explicit\nprefix (`kundenbetreuung*`), AND, OR, NOT, parentheses and followed-by.\nThe Fantastic.jobs name `description_advanced` is accepted as an alias; theirs\nalso searches the title, ours the advert text only. A phrase matches\nthe words in that order, anywhere in the body. Broad phrases over\nmillions of adverts are the most expensive query this API can be\nasked; prefer a country or category alongside. A plain value keeps\nthe old AND-of-words behaviour. Case-insensitive in every script\n(2026-10-23) for words the advert writes in lower case, Capitalised\nor in capitals. An accented term also finds the unaccented spelling;\nan unaccented term does not yet find accented advert text.\n\nLive postings only (2026-11-04): with `status=closed` or `status=any`,\nand on /v1/jobs/closed, /v1/jobs/expired and closed exports, it\nanswers **422** `description_contains_live_only`. Use `title` or `q`\nfor closed postings.\n",
        "in": "query",
        "name": "description_contains",
        "schema": {
          "type": "string"
        }
      },
      "EmploymentType": {
        "description": "Comma-separated: full-time, part-time, contract, temporary, internship\n(case-insensitive; full_time / part_time are accepted too); `not_stated`\nselects rows with none. Matches exactly the employment_type value the\nresponse shows, including values read from the posting page by the\nverification sweep (since 6 Oct 2026; before that only the harvested\nvalue was matched, about a sixth as many rows).\nCoverage, measured 23 Oct 2026: 39.3% of served rows carry a value\n(942,302 of 2,399,121); the rest say not_stated, because the source\npublishes no employment type. A contract-duration word alone\n(Permanent, Regular, CDI, Employee) is not read as Full-time.\n",
        "in": "query",
        "name": "employment_type",
        "schema": {
          "type": "string"
        }
      },
      "Engagement": {
        "description": "Comma-separated (OR, up to 8, case-insensitive): `employee`, `vendor`,\n`other`, or `unknown` (alias `not_stated`). The employment RELATIONSHIP\nthe posting states: `employee` is payroll employment under the posting\ncountry's law (including temp-agency and zero-hours work); `vendor` is\na commercial/self-employed arrangement (freelance, B2B, 1099, C2C,\nBrazilian PJ); `other` is a stated hybrid national form that everyday\nunderstanding puts on neither side (Polish umowa zlecenie, Italian\nco.co.co., umbrella/portage arrangements, statutory non-employment\ninternships, volunteering). The raw national term is retained\ninternally and refines these over time. The row value is an ARRAY\n(dual-option adverts such as \"CLT ou PJ\" carry both options, main one\nfirst); the filter matches any element. `unknown` selects rows where\nthe posting does not establish the relationship (nothing is ever\ninferred from silence), so at launch most rows are `unknown`. An\nunrecognised value is a 422 naming the legal list.\n",
        "in": "query",
        "name": "engagement",
        "schema": {
          "type": "string"
        }
      },
      "ExcludeCategory": {
        "in": "query",
        "name": "exclude_category",
        "schema": {
          "type": "string"
        }
      },
      "ExcludeCompanyDomain": {
        "description": "Same vocabulary as company_domain, removed instead of kept.",
        "in": "query",
        "name": "exclude_company_domain",
        "schema": {
          "type": "string"
        }
      },
      "ExcludeCompensationType": {
        "description": "Exclude postings the commission-only rule flagged (db/370). The only\nlegal value is `commission_only`, matching the API's existing\nexclude_* convention (exclude_category, exclude_country, ...).\n",
        "in": "query",
        "name": "exclude_compensation_type",
        "schema": {
          "enum": [
            "commission_only"
          ],
          "type": "string"
        }
      },
      "ExcludeCountry": {
        "in": "query",
        "name": "exclude_country",
        "schema": {
          "type": "string"
        }
      },
      "ExcludeProvider": {
        "description": "Same vocabulary as `provider`, removed instead of kept.",
        "in": "query",
        "name": "exclude_provider",
        "schema": {
          "type": "string"
        }
      },
      "ExcludeSourceType": {
        "in": "query",
        "name": "exclude_source_type",
        "schema": {
          "type": "string"
        }
      },
      "Family": {
        "description": "Alias for `category` (the facet key in /v1/meta/facets is named\n`family`; the filter parameter was `category`). Both names are\naccepted everywhere `category` is.\n",
        "in": "query",
        "name": "family",
        "schema": {
          "type": "string"
        }
      },
      "HasDescription": {
        "description": "`true` returns only the 2,376,694 live rows (97.3%) that carry a description.",
        "in": "query",
        "name": "has_description",
        "schema": {
          "type": "boolean"
        }
      },
      "HasSalary": {
        "description": "`true` (and `structured`) returns only rows whose salary the SOURCE published: the meaning this parameter has always had, kept so that adding derived salaries does not change the results of a query you already ship. `any` also includes figures we read out of the advert text (`salary_source: parsed_description`, reported as `inferred`). AI estimates are never published under any value.\n",
        "in": "query",
        "name": "has_salary",
        "schema": {
          "enum": [
            "true",
            "structured",
            "any"
          ],
          "type": "string"
        }
      },
      "IncludeDescription": {
        "description": "Return the full advert text in a `description` field. Off by default:\ndescriptions averaged 2,581 bytes (measured 5 Aug 2026), so a 200-row page would be a ~516 KB\nresponse nobody asked for. With this on, `limit` may not exceed 50:\na larger request is refused with 422 rather than quietly clamped.\nPersonal email addresses in the text are replaced with\n`[personal contact removed]`; company mailboxes and phone numbers are\nkept (see the `description` field).\n",
        "in": "query",
        "name": "include_description",
        "schema": {
          "type": "boolean"
        }
      },
      "IncludeEmbedding": {
        "description": "Opt-in extras on the job rows. The only value today is `embedding`:\neach job (and, on the changes feed, each event job) then carries an\n`embedding` object `{model, dim, normalized, vector}`. The vector is the\n1024-dimension Matryoshka tier of Qwen3-Embedding-8B (the first 1024 of\nits 4096 dimensions, re-normalised to unit length), `float32`, built\nfrom the posting title, company, location and the start of the advert text (one per line), with **no** instruction prefix.\n\n**Query vectors.** To search these vectors with your own query, embed\nthe query with the same model and the instruction prefix\n`Instruct: Given a web search query, retrieve relevant job postings that match the query\\nQuery: \u003cyour text\u003e`\n(a real newline between the two lines), keep the first 1024 dimensions,\nL2-normalise, and use cosine or dot product. Do **not** apply the\nprefix to documents, and do not mix vectors from a different model.\n\nA job with no vector yet (the newest postings are still being\nbackfilled, and closed jobs may have none) carries `vector: null` and a `reason`: `no_vector`, or\n`vectors_unavailable` when the vector service did not answer in time\n(the rows are still served and billed as usual; retry for the vectors).\nOff by default: without the parameter the response is byte-for-byte what\nit was. A page is 1.3 MB per 100 rows, so `limit` may not exceed 100\n(422 `limit_too_large`). Any other value is a 422 `bad_include`. Every API key,\nfree included; the keyless mirror answers 403 `key_required`. **Not\ncharged as records**: the meter counts the rows served, exactly as\nwithout the parameter.\n",
        "in": "query",
        "name": "include",
        "schema": {
          "enum": [
            "embedding"
          ],
          "example": "embedding",
          "type": "string"
        }
      },
      "IncludeTotal": {
        "description": "Add `total_estimate` and `total_estimate_status` to the response: the\nnumber of rows matching the filters, exact up to 10,000 and\npage-independent. Costs one extra bounded query (at most 4 seconds;\npast that the page is still returned, with\n`total_estimate_status: timed_out`). Not charged as records.\n",
        "in": "query",
        "name": "include_total",
        "schema": {
          "default": false,
          "type": "boolean"
        }
      },
      "Language": {
        "description": "ISO 639-1 two-letter language code of the posting text (e.g. `de`, `fr`, `en`).\nComma-separated, up to 12 languages (OR).\n",
        "in": "query",
        "name": "language",
        "schema": {
          "type": "string"
        }
      },
      "LanguageExclude": {
        "description": "Exclude postings in these ISO 639-1 language codes.\nComma-separated, up to 12 languages. Rows with undetected language are kept.\n",
        "in": "query",
        "name": "language_exclude",
        "schema": {
          "type": "string"
        }
      },
      "ListedAfter": {
        "description": "Only rows that entered this API after this instant (date, RFC3339 timestamp, or since 9 Nov 2026 a relative\nvalue: now, now-15m, now-2h, now-1d, today, yesterday, in UTC), as recorded by the\nserved-set ledger behind /v1/changes: new rows, and rows that came back after a withdrawal or\nre-opened after a closure, each counted from its latest entry. Use it to poll for new jobs, on any\nplan. posted_after cannot do that: posted_at is the employer's own date and is often days older than\nthe moment a job reaches the API. Rows served since before 2026-10-23 06:11 UTC count from their\nfirst_seen_at. Poll with listed_after = \u003cstart of your previous poll\u003e minus a few minutes and\nde-duplicate on id, or use `since` (no overlap, no de-duplication). On /v1/jobs/closed it selects closed rows that had entered after this instant.\n",
        "in": "query",
        "name": "listed_after",
        "schema": {
          "type": "string"
        }
      },
      "ListedBefore": {
        "description": "Only rows that entered this API before this instant (exclusive), on the same served-set ledger as\nlisted_after. With listed_after it is a range. Accepts the same values as listed_after, relative ones\nincluded. Since 9 Nov 2026.\n",
        "in": "query",
        "name": "listed_before",
        "schema": {
          "type": "string"
        }
      },
      "MaxSalary": {
        "description": "Upper bound on salary_min_annual_eur. Same scope as min_salary.",
        "in": "query",
        "name": "max_salary",
        "schema": {
          "type": "number"
        }
      },
      "MinSalary": {
        "description": "Lower bound on `salary_min_annual_eur`. Only rows whose salary could be\nnormalised to an annual EUR figure can match (the current share is on\n/public/coverage, field salary_eur), so this is a narrow filter by\nnature, not a broken one. It compares every normalisable figure,\npublished by the source or read out of the advert text\n(`field_sources.salary` and `salary_source` say which); add\n`has_salary=true` to compare only salaries the source published.\n",
        "in": "query",
        "name": "min_salary",
        "schema": {
          "type": "number"
        }
      },
      "PostedAfter": {
        "description": "Date, RFC3339 timestamp, or a relative value (now, now-15m, now-2h, now-1d, today, yesterday; UTC).",
        "in": "query",
        "name": "posted_after",
        "schema": {
          "type": "string"
        }
      },
      "PostedBefore": {
        "description": "Only rows posted before this instant (exclusive). With posted_after it is a range. Date, RFC3339\ntimestamp or a relative value: now, now-30s, now-15m, now-2h, now-1d, today, yesterday (UTC, resolved\nonce per request; today and yesterday are 00:00 UTC). Since 9 Nov 2026.\n",
        "in": "query",
        "name": "posted_before",
        "schema": {
          "type": "string"
        }
      },
      "Provider": {
        "description": "Comma-separated list of the exact source systems to include, e.g.\n`greenhouse,lever,workday`. This is the ATS or board a vacancy came\nfrom, finer than source_type which buckets them. A name we do not\npublish is a 422, never a silently empty page. Up to 12 values.\n",
        "in": "query",
        "name": "provider",
        "schema": {
          "type": "string"
        }
      },
      "Q": {
        "description": "Full-text over title, company name and location, NOT the description.\nThat is deliberate, not a limitation: use `description_contains` for\nthe advert body. Without extended syntax the words are ANDed and each\nmatches whole words only (no stemming): `q=engineer` does not match\n`engineering`. Boolean syntax (the same on `title`, `title_exclude`,\n`description_contains` and `company_name_contains`; full reference at\n/docs/api/filtering#query-grammar):\n- `\"customer support\"` or `'customer support'`: exact phrase, adjacent and in order.\n- `entwickler*` or `entwickler:*`: prefix match, which finds `entwicklerin` and the\n  German gender-inclusive `entwickler/in`. A prefix needs 3 or more characters.\n  A bare word is always exact: since 2026-11-10 there is no automatic\n  prefix (until then a word of 5+ letters was prefixed once any syntax\n  was used, so `react OR vue` also matched `Reactor`).\n- `a b`, `a AND b`, `a \u0026 b`: both.\n- `a OR b`, `a | b`: either.\n- `-berlin`, `!berlin`, `NOT berlin`: exclude. `-` and `!` must touch the term\n  or group; a free-standing one is punctuation.\n- `(a OR b) c`: parentheses group.\n- `machine \u003c-\u003e learning`: followed by (adjacent, in order); `data \u003c2\u003e scientist`:\n  followed within 2 positions (1 to 10).\nPrecedence: NOT, then followed-by, then AND, then OR. `a b OR c d` is\n`(a b) OR (c d)` (since 2026-10-25) and `a | b \u0026 c` is `a | (b \u0026 c)`.\nThis is the Fantastic.jobs `_advanced` notation, so their expressions\npaste unchanged. `\u0026` and `|` count as operators when the value joins every\npair of terms with an operator, or uses other syntax; in a pasted title such as\n`Shift Lead | Philadelphia` they stay punctuation, and `R\u0026D` is one word.\nLimits: a boolean expression holds at most 32 terms (a plain value has no such\nlimit, as before); parentheses nest at most 8 deep in any value; every value is under 500 bytes. Malformed input is\nrefused with **422** `query_syntax`, over a limit with **422**\n`query_too_complex`; both name the character position and nothing is\ncharged.\nMatching is case-insensitive in every script and accent-insensitive\n(2026-10-23): `λογιστής`, `Λογιστής` and `ΛΟΓΙΣΤΗΣ` are one query,\nand `developpeur` finds `Développeur` as `développeur` does.\nLocalized syntax examples, one per customer language: German\n`entwickler*` and the exact phrase `\"software entwickler\"`; French\n`développeur*` and `\"service client\"`; Spanish\n`desarrollador*` and `\"marketing digital\"`; Dutch `verpleegkundige*`\n(prefix finds the plural). Works the same in every language the\nledger carries.\n",
        "in": "query",
        "name": "q",
        "schema": {
          "type": "string"
        }
      },
      "Region": {
        "description": "Comma-separated ISO 3166-2 subdivision codes or English names, up to 60: `GB-DEV` or `Devon`, `US-OH` or `Ohio`,\n`CA-ON`, `AU-WA`. Covers US states, Canadian provinces, Australian states and territories, UK nations and about 50\nUK counties. A row whose subdivision is not established is never returned by a region filter and never excluded\nby the other filters. An unknown value is a 422 `bad_region`.\n",
        "in": "query",
        "name": "region",
        "schema": {
          "type": "string"
        }
      },
      "Remote": {
        "description": "`remote`, `hybrid`, `on_site`, or `not_stated`.",
        "in": "query",
        "name": "remote",
        "schema": {
          "type": "string"
        }
      },
      "RemoteConfirmed": {
        "description": "`true` returns only listings whose remote status the SOURCE stated:\n509,137 of 2,443,847 live rows (20.8%).\nWithout it you also receive the 1,932,297\n(79.1%) where we inferred it from the location text, the\ntitle, or the presence of a named workplace city.\n",
        "in": "query",
        "name": "remote_confirmed",
        "schema": {
          "type": "boolean"
        }
      },
      "RequireFields": {
        "description": "Comma-separated. Returns only rows where EVERY named field is\n`published` in `field_sources`, a value the source carried, never one\nwe derived. The response then also contains a `completeness` object\nsaying how many live rows carry each of them.\n\nThis is the answer to \"only 16.5% of your rows have a\nsalary\". They do, and `require_fields=salary` returns\n403,533 rows of which 100% carry a figure an employer\nactually wrote, with no estimate anywhere in the response. Check the\nper-country split at `/public/coverage/countries` before you spend a\nrecord.\n\n`category` and `seniority` are refused with 422: both are read off the\njob title by our classifier, so they are `inferred` by construction and\nno row can ever satisfy them. An empty page would look like a coverage\nproblem; the error says what it is.\n\n`source_type` is accepted and currently matches nothing: the per-row\nclassification exists in the schema and no live row carries one yet. The\n`completeness` block reports that as a count rather than leaving you to\ninfer it from an empty page.\n",
        "in": "query",
        "name": "require_fields",
        "schema": {
          "example": "salary,description",
          "type": "string"
        }
      },
      "Seniority": {
        "description": "Comma-separated; `not_stated` selects rows with none.",
        "in": "query",
        "name": "seniority",
        "schema": {
          "type": "string"
        }
      },
      "Since": {
        "description": "The resumable poll (9 Nov 2026). On /v1/jobs it selects rows that entered this API after since (as\nlisted_after does), and on /v1/jobs/closed rows that closed after since, up to an upper bound the\nserver fixes on the first page: the newest instant at which every earlier entry (or closure) is\ncommitted and visible, so no row can later appear behind it. Every page of the walk returns that\nbound as `next_since`, an opaque token (today `ns1_` and digits; treat it as a string). After the\nlast page, store `next_since` and send it as `since` on your next poll: no gap and no duplicate,\nwith no overlap window to de-duplicate. Page with `next_cursor` as usual: the cursor carries the\nbound, so the window does not move while you page. The first call takes a time instead of a token:\na date, an RFC3339 timestamp or a relative value (now-1d, today, ...). The token does not expire.\nCannot be combined with listed_after or listed_before (on /v1/jobs/closed: closed_after or\nclosed_before): 422 `conflicting_parameters`. A row that re-enters later (re-opened, or back after a\nwithdrawal) appears again on the poll that covers its new entry.\n",
        "in": "query",
        "name": "since",
        "schema": {
          "type": "string"
        }
      },
      "SortRelevance": {
        "description": "`sort=relevance` orders by where and how the query matches instead of\nrecency: relevance-scored, band-weighted (title, category, company,\nlocation), tolerant of equivalents and abbreviations. Ordering-only:\nscores are comparable within a response, never across queries. Each\nrow then carries a `relevance` object `{score, tier}` (tier one of\nexact, synonym, abbreviation, typo). Requires `q` and an API key;\n`q` must be under 200 bytes; other sort values are rejected.\nDeployment-gated. While the ranked mode is not enabled on the\ndeployment (the case today), any `sort` value is refused with\n**422** `sort_unavailable` and nothing is charged; results are always\nnewest first. It is never silently ignored.\n",
        "in": "query",
        "name": "sort",
        "schema": {
          "enum": [
            "relevance"
          ],
          "type": "string"
        }
      },
      "SourceType": {
        "description": "Comma-separated provenance filter. The legacy spellings\n`employer_ats`, `government` and `direct` are still accepted and map\nonto `ats`, `public_agency` and `career_site`.\n\nFilter values are matched case-insensitively: `category=engineering`\nand `category=Engineering` are the same query. Enumerate the legal\nvalues with /v1/meta/facets.\n",
        "in": "query",
        "name": "source_type",
        "schema": {
          "examples": [
            "ats",
            "career_site,public_agency"
          ],
          "type": "string"
        }
      },
      "SponsorRegister": {
        "description": "Opt-in, added 10 Nov 2026. Only jobs that carry, in `sponsor_registers`, an official\ngovernment sponsor or work permit register of these countries. A register counts only for\njobs located in its country (or open to it, for a multi-country role), so\n`sponsor_register=GB` returns GB jobs at employers on the UK register:\na comma separated list of GB (UK is accepted), NL, US, CA, IE, DK, or `any` for any\npublished register. A country whose register is not published yet is accepted and\nmatches nothing until it is. A posting that names another employer than the company it\nwas collected under (an ATS tenant or a staffing firm posting for a client) never\nmatches. Appearing on a register is a public fact as of the register's date, not a\npromise that the employer will sponsor a visa for this job. Absent: no change to the\nquery. Facets, counts and metering are unchanged. Any other value is a 422\n`bad_sponsor_register` and no records are billed.\n",
        "in": "query",
        "name": "sponsor_register",
        "schema": {
          "example": "GB,NL",
          "type": "string"
        }
      },
      "State": {
        "description": "Comma-separated two-letter US state codes, e.g. `OH` or `OH,TX`.\nAbsent where we could not establish the state from the source;\ndeliberately absent for ambiguous city names, so this filter\nunder-reports rather than placing a job in the wrong state.\n",
        "in": "query",
        "name": "state",
        "schema": {
          "type": "string"
        }
      },
      "Title": {
        "description": "Full-text over the job title only, e.g. `?title=engineer`. It ANDs\nwith every other filter, including `?description_contains=kubernetes`\nover the advert body, but the two full-text filters together are the\nmost expensive query this API can be asked, because both indexes are\nGIN and the matching rows still have to be fetched to be ordered by\nposted_at. Send them together on a narrow country or category, not on\nthe whole ledger.\n\nBoolean syntax, exactly as on `q` and matched against the title only:\nphrases (`\"software entwickler\"`), explicit prefix (`entwickler*`, `manag:*`),\nAND (space, `AND`, `\u0026`), OR (`OR`, `|`), NOT (`-`, `!`, `NOT`), parentheses,\nfollowed-by (`\u003c-\u003e`, `\u003cN\u003e`). Example: `(react | vue) \u0026 (node | golang) \u0026 !aws`.\nA plain value keeps the old AND-of-words behaviour. This is the Fantastic.jobs\n`title_advanced` notation, and `title_advanced` is accepted as an alias of `title`.\nCase-insensitive in every script and accent-insensitive, as `q`\n(2026-10-23): `title=ärztin`, `title=Ärztin` and `title=arztin`\nare one query.\n",
        "in": "query",
        "name": "title",
        "schema": {
          "type": "string"
        }
      },
      "TitleExclude": {
        "description": "Drop rows whose title matches these words. Same matching, and the\nsame boolean syntax, as `title`.\n",
        "in": "query",
        "name": "title_exclude",
        "schema": {
          "type": "string"
        }
      },
      "VerifiedAfter": {
        "description": "Only rows whose last_verified_at (the last positive confirmation at the source, see the Job schema) is at or after this instant. Date, RFC3339 timestamp, or a relative value (now-1d, today, ...; UTC).",
        "in": "query",
        "name": "verified_after",
        "schema": {
          "type": "string"
        }
      },
      "VerifiedBefore": {
        "description": "Only rows whose last_verified_at is before this instant (exclusive). With verified_after it is a range.\nAccepts the same values as verified_after, relative ones included. Since 9 Nov 2026.\n",
        "in": "query",
        "name": "verified_before",
        "schema": {
          "type": "string"
        }
      },
      "VisaText": {
        "description": "Opt-in. Only jobs whose `work_visa_text.evidence_level` is this value: `stated_open` (the advert\nsays the employer helps with the visa or permit, and says nothing that closes the job) or\n`stated_closed` (the advert says there is no sponsorship, asks for an existing right to work, or\nlimits the job to citizens). It selects what adverts say; it is not advice and not a decision on\nany person's case. Jobs that were not read (`not_assessed`) never match; the countries read so far\nare in `/v1/help` (`work_visa_text.coverage`). Absent: no change to the query. Facets, counts and\nmetering are unchanged. Any other value is a 422 `bad_visa_text` and no records are billed.\n",
        "in": "query",
        "name": "visa_text",
        "schema": {
          "enum": [
            "stated_open",
            "stated_closed"
          ],
          "type": "string"
        }
      },
      "WorkingSchedule": {
        "description": "Comma-separated (OR, case-insensitive): `full_time`, `part_time`,\n`flexible`, or `unknown` (alias `not_stated`). The stated schedule;\n`flexible` covers adverts offering either schedule. Distinct from the\nfrozen `employment_type` field, which this API keeps unchanged.\n",
        "in": "query",
        "name": "working_schedule",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "401": {
        "$ref": "#/components/responses/Unauthorized"
      },
      "429": {
        "$ref": "#/components/responses/RateLimited"
      },
      "BadRequest": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "A parameter the endpoint does not take. `unknown_parameter`: the name\nis not a parameter of this endpoint; the message names it and, when a\nvalid parameter is within a small edit distance, suggests it\n(\"unknown parameter: 'countyr'; did you mean 'country'?\").\n`unsupported_parameter`: a real parameter of another endpoint that has\nno meaning here (for example `limit` on `/v1/export`). Refused before\nthe meter: nothing is charged.\n"
      },
      "NotFound": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "No such row."
      },
      "PlanUpgradeRequired": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "A 403, and the body says which layer refused it. `plan_upgrade_required`: the endpoint is not included in your plan, and `X-JOA-Required-Feature` names the missing entitlement, `delta_feed` or `bulk_export`. See https://jobopportunitiesapi.org/api for the tiers that include it. `key_endpoint_not_configured`: the key is not configured for that endpoint, which is a setting on the key and never a plan limit; the message names the endpoint and says how to change it. The /v1/me family is always on whatever a key allows. `paid_feature`: a parameter of this request (`status=closed`, `include_poster_type`) needs a paid key. (The spelling `upgrade_required`, documented here until 6 Nov 2026, was never what the running API sends.)\n"
      },
      "RateLimited": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/LimitError"
            }
          }
        },
        "description": "Over your plan's per-minute or per-day limit. `Retry-After` says how long (seconds to the next minute boundary, or to UTC midnight on a daily breach). The body says exactly when the limit resets (`resets_at`, `resets_at_text`) and, when a higher plan exists, links a same-key upgrade (`upgrade_url`).\n",
        "headers": {
          "Retry-After": {
            "description": "Seconds until the limit resets.",
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Reset": {
            "description": "Unix seconds of the next UTC midnight, when the daily counter resets.",
            "schema": {
              "type": "integer"
            }
          }
        }
      },
      "RecordQuotaExhausted": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/LimitError"
            }
          }
        },
        "description": "The plan's monthly RECORD allowance is spent. Distinct from 429: a 429 means slow down and retry, a 402 means the licence is used up until the allowance resets. The monthly window is the CALENDAR month in UTC: it resets on the 1st of the next month at 00:00 UTC, and the body gives the exact instant. Do not retry before then. Every metered response carries `X-RateLimit-Records-Remaining` and `X-RateLimit-Records-Reset` (the reset instant, Unix seconds), so this is visible long before it happens.\n",
        "headers": {
          "X-RateLimit-Records-Limit": {
            "description": "Records included in the plan this month.",
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Records-Reset": {
            "description": "Unix seconds of the instant the monthly allowance resets (the 1st of next month, 00:00 UTC). There is no Retry-After on a 402.",
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Records-Used": {
            "description": "Records consumed this month.",
            "schema": {
              "type": "integer"
            }
          }
        }
      },
      "SponsorLookup": {
        "content": {
          "application/json": {
            "schema": {
              "properties": {
                "count": {
                  "type": "integer"
                },
                "data": {
                  "items": {
                    "$ref": "#/components/schemas/SponsorLookupResult"
                  },
                  "type": "array"
                },
                "legal_note": {
                  "description": "Added 11 Nov 2026. The text of the `immigration_information` note, on every answer: \"This\ninformation is not immigration advice, legal advice or any other service to candidates. It is\nprovided for information only and may be incomplete, inaccurate or out of date. Before starting\nany immigration or employment process, contact a qualified, certified professional.\" Show the\nlegal_note with this information, unless you are an authorised immigration adviser presenting it\nwithin your regulated service. If you omit it, you take full responsibility.\n",
                  "type": "string"
                },
                "legal_note_code": {
                  "description": "Added 11 Nov 2026. Always `immigration_information` on a lookup answer.",
                  "type": "string"
                }
              },
              "type": "object"
            }
          }
        },
        "description": "One result per employer, in request order."
      },
      "Unauthorized": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Missing, unknown, revoked or expired key. All four are reported identically."
      },
      "Unprocessable": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "A parameter value we will not guess at: an unknown source_type or provider, an unparseable timestamp, a malformed cursor, a `limit` outside 1-200 or not a whole number (`bad_limit`), a flag that is not true/false (`bad_boolean`), a comma-separated list longer than its maximum (`too_many_values`), a text\nfilter the query grammar cannot honour (`query_syntax`: an unmatched\nparenthesis, an empty group, an operator with no term on one side, since 2026-10-25; the message names the\ncharacter position) or a boolean expression over the grammar limits (`query_too_complex`, since 2026-11-10; plain values have no such limit). Nothing is charged. The one visible reduction: a `limit` within 1-200 but above the plan's page cap is reduced to the cap and flagged in `X-JOA-Limit-Applied`. Unknown parameter NAMES are a 400 (`BadRequest`), never ignored.\n"
      }
    },
    "schemas": {
      "Company": {
        "properties": {
          "careers_url": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "first_seen": {
            "type": "string"
          },
          "industry": {
            "type": "string"
          },
          "logo": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "open_roles": {
            "description": "Roles retrievable from THIS API. Never a number the API cannot honour.",
            "type": "integer"
          },
          "org_type": {
            "type": "string"
          },
          "own_site_roles": {
            "description": "Vacancies seen on the company own careers page.",
            "type": "integer"
          },
          "sectors": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "slug": {
            "type": "string"
          },
          "source_types": {
            "description": "`aggregator` and `agency` are reserved and match no rows today; see the source_type enum.\n",
            "items": {
              "enum": [
                "ats",
                "career_site",
                "public_agency",
                "aggregator",
                "agency"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "website": {
            "type": "string"
          },
          "website_verified": {
            "description": "When we fetched this domain and found the company own name on it.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "CompanyPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Company"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "limit": {
            "type": "integer"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          },
          "offset": {
            "type": "integer"
          }
        },
        "required": [
          "data",
          "next_cursor",
          "has_more"
        ],
        "type": "object"
      },
      "Error": {
        "properties": {
          "docs": {
            "type": "string"
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "FieldSources": {
        "description": "Per-field provenance. `published` means the value was carried by the\nsource. `inferred` means WE produced it. It may be right, but it is not a\nquotation. `absent` means no value, which is a different failure from a\nguess and is reported as such.\n\n`category` and `seniority` are ALWAYS `inferred`: both are read off the\njob title by a classifier, never from a field the employer filled in.\n\n`salary` is `published` when the source stated it in a field\n(`salary_source: structured`), and `inferred` when we read it out of the\nadvert text (`salary_source: parsed_description`). It is never an\nestimate: the projection refuses to emit AI salary predictions\nat all, so a modelled figure cannot reach this API by any route.\nAmounts are always the employer's own figures. Some sources state an\namount and never its pay period or currency; where exactly one reading\nis possible (a one-currency country whose amount fits, or amounts whose\nmagnitude can only be one period for that country and currency), we\nfill the missing unit, and `salary_period` / `salary_currency` below\nthen read `inferred` while `salary` stays `published`. Anything less\nobvious stays absent.\n\n`region`, `expires_at`, `description_length`, `source_requisition_id`,\n`employer_website`, `salary_max`, `salary_currency` and `salary_period`\nwere added with db/144, which moved the fields parsed out of the source's\nown page into a side table (`joa.listing_extract`). The payload coalesces\nthe listing column with the extracted one, preferring whatever the row\nalready carried, and these keys say whether a value is there: a value\nthat came from the source is `published`, a missing one is `absent`.\n\nEvery key on this object is ALWAYS present on every job (the vocabulary\nis the value, not the presence), so a client can bind the whole shape.\n",
        "properties": {
          "agency": {
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "category": {
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "compensation_type": {
            "description": "Always `inferred` when the `compensation_type` key is present on\nthe job object (db/370): a rule's reading of the description,\nnever a structured field a source publishes. `absent` means the\nrule found no commission-only claim.\n",
            "enum": [
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "contract_category": {
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "country": {
            "description": "How the job's `country` was obtained. `published`: the recorded origin says the\nsource's own countries array carried it (before 26 Oct 2026 this keyed off the\nsource's own location text with no marker against it). `inferred`: a rule of ours\n(gazetteer, state code) or a repair set it, or the gazetteer and a language model\nagreeing (`country_confidence: \"high\"`, measured precision 99.5%).\n`llm_inferred`: LOW TRUST. A language model read the location text and named the\ncountry with no second signal; `country_confidence` is `\"low\"` and the measured\nprecision of this class is about 95% (hand-checked sample of 120 rows; 98% on an\nindependent model check of 400 rows), against about 99% for the other classes.\nFilter on `field_sources.country` in your own code to keep only the higher-trust\nvalues. `unknown`: the row has a country but nothing records where it came from,\nthe honest label for a legacy value. `absent`: the job has no country.\n",
            "enum": [
              "published",
              "inferred",
              "llm_inferred",
              "unknown",
              "absent"
            ],
            "type": "string"
          },
          "description": {
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "description_length": {
            "description": "Computed from the same octet_length as description, so the two cannot\ndisagree: published when the row carries text, absent when it does\nnot.\n",
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "employer_website": {
            "description": "Provenance of employer_website. Like source_requisition_id it only\never comes from the page the sweep parsed, so it is published or\nabsent, never inferred.\n",
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "employment_type": {
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "engagement": {
            "description": "Provenance of the engagement array (db/232): `published` when the\nsource's own field or page stated the relationship, `inferred` when\nan audited deterministic rule of ours established it (the payload\nthen also carries engagement_confidence), `absent` when the posting\ndoes not establish it (the value key is then omitted and\n`?engagement=unknown` selects the row). Never inferred from silence.\n",
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "expires_at": {
            "description": "Provenance of expires_at: published when the row carries one, from\neither source (see the Job schema), absent when it does not.\nA LIVE row carries it whenever the posting states its own\nvalidThrough date (corrected 6 Nov 2026: this said \"absent while\nthe vacancy is live\"; 14.2% of live rows carry one, and a stated\ndate can already be in the past while the source still lists the\nrole).\n",
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "language": {
            "description": "\"detected\" when the row publishes a language (our detector's reading of the advert text, not the source's declaration), and \"absent\" while the row's language is null (the key was omitted then until 17 Oct 2026). It never reads published or inferred.\n",
            "type": "string"
          },
          "location": {
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "occupation": {
            "description": "ESCO occupation (v1.2.1). `inferred` whenever `esco_occupation_uri`\nis present on the job object: the normalised title equals a preferred\nESCO label of exactly one occupation (an exact match, not a guess\nfrom similarity); it is our automated inference, never something the\nemployer or the source states. `absent` means no exact match, and the\nthree occupation keys are omitted. Never `published`.\n",
            "enum": [
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "posted_at": {
            "description": "published when the source stated the date or timestamp. Workday publishes a date only (see posted_at_precision): its rows read inferred until the posting's own start date has been read from Workday (on the next re-verification, about daily), because the list API only says \"Posted N Days Ago\" and we derive the date from that.\n",
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "region": {
            "description": "published when the row carries a region, absent when it does not. It\ndoes NOT separate the region the source declared from the ones db/078\nderives from the location text or the city gazetteer, and it does not\nseparate the listing column from the value extracted off the page\n(db/144). Read it as \"we established a region\", not as a quotation.\n",
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "remote": {
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "salary": {
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "salary_currency": {
            "description": "Provenance of salary_currency. The group's verdict, with one exception:\n`inferred` beside `salary: published` means the source stated the amount\nbut never the currency, and we filled the only possible one (one-currency\ncountry, amount fits). The amount itself is still the employer's.\n",
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "salary_max": {
            "description": "Provenance of salary_max, and always the same verdict as salary:\npublished only when the source stated the figure in a field of its\nown, inferred when we read it out of the advert text, absent when\nthere is no figure.\n",
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "salary_period": {
            "description": "Provenance of salary_period. The group's verdict, with one exception:\n`inferred` beside `salary: published` means the source stated the amount\nbut never the period, and the magnitude allows only one reading for that\ncountry and currency (19 USD in the US is hourly pay, 93,600 USD yearly\npay; anything in between stays absent). The amount itself is still the\nemployer's.\n",
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "seniority": {
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "source_requisition_id": {
            "description": "Provenance of source_requisition_id. The value only ever comes from\nthe page the verify sweep parsed (db/144), so this is published or\nabsent, never inferred.\n",
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "source_type": {
            "description": "`inferred` when the value is the provider's default class;\n`published` when the row itself was classified upstream.\n\nTODAY THIS IS ALWAYS `inferred`: the row-level column is null on\nevery live listing, so the provider's class is the only path taken.\n`published` is reserved for when per-row classification lands. Do not\nbuild a filter that expects it to appear.\n",
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          },
          "working_schedule": {
            "enum": [
              "published",
              "inferred",
              "absent"
            ],
            "type": "string"
          }
        },
        "required": [
          "remote",
          "employment_type",
          "engagement",
          "contract_category",
          "agency",
          "working_schedule",
          "category",
          "seniority",
          "salary",
          "salary_max",
          "salary_currency",
          "salary_period",
          "location",
          "country",
          "region",
          "posted_at",
          "description",
          "description_length",
          "source_type",
          "expires_at",
          "source_requisition_id",
          "employer_website"
        ],
        "type": "object"
      },
      "Job": {
        "properties": {
          "agency": {
            "description": "Who the employer of record is: `direct`: the advertiser; `agency`:\na temporary-work agency (the engagement is then employee, per EU\nand national law, and contract_category describes the contract with\nthe agency: permanent agency contracts exist); `umbrella`: an\numbrella / portage company. OMITTED when not established\n(`?agency=unknown`). No confidence key by design.\n",
            "enum": [
              "direct",
              "agency",
              "umbrella"
            ],
            "type": "string"
          },
          "apply_url": {
            "type": "string"
          },
          "attribution": {
            "description": "Show the listing with these words. Present on roles an employer pushed to us directly, and on every row of a source whose licence\nrequires it to be named (Norway: \"NAV (arbeidsplassen.no)\", from the NAV job vacancy feed; UK: \"NHS Jobs\", from the NHS Jobs vacancy feed,\nwhose rows contain public sector information licensed under the Open Government Licence v3.0, https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/:\nkeep the credit and the link to the advert and acknowledge the licence; France: \"Emploi-Territorial\" and \"Choisir le service public\",\nfrom the two French public service job portals, re-used under the Licence Ouverte 2.0 (Etalab), https://www.etalab.gouv.fr/licence-ouverte-open-licence/:\nkeep the credit, the link to the offer page and the date of last update, which is last_verified_at (the last time JOA read the offer at\nits source; posted_at is the publication date the source states)). Absent on every other row.\n",
            "type": "string"
          },
          "canonical_url": {
            "description": "Present only on roles an employer pushed to us directly: the role's own page, where people apply and which search engines should index. Link to it, not to our page. Absent on every other row.\n",
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "category_confidence": {
            "description": "Classifier confidence in `category`. Below 0.6 no category is published at all, so this is always null or \u003e= 0.6.",
            "type": [
              "number",
              "null"
            ]
          },
          "city": {
            "type": "string"
          },
          "closed_at": {
            "description": "JOA records as the closure date the day its daily verification confirmed that an advert had gone. Before late September 2026 that verification ran in large catch-up batches, so closure dates recorded before then show when JOA confirmed a closure, not when the employer closed the role; daily verification applies from late September 2026.",
            "type": [
              "string",
              "null"
            ]
          },
          "closed_reason": {
            "enum": [
              "expired_upstream",
              "not_seen",
              "apply_link_dead",
              "employer_closed",
              "deadline_passed",
              "aggregator_host",
              "generic_apply_url",
              "portal_apply_url",
              "superseded_by_jobtech_loader",
              "ai_verified_closed",
              null
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "company": {
            "type": "string"
          },
          "company_logo": {
            "type": "string"
          },
          "company_more_roles": {
            "description": "The additional-roles count of the collapsed shape (24 Oct 2026).\nPresent on EVERY row when the request used `collapse=company`,\n0 included: the number of further roles of this employer that the\nrequest read and hid behind this row. Absent otherwise, so a payload\nwithout the parameter keeps its exact bytes.\nIt counts the rows the request read (a request reads at most 2,000\nrows to fill a collapsed page), so roles past that are not counted.\n`?company=\u003ccompany_slug\u003e` lists an employer's complete set.\n",
            "type": "integer"
          },
          "company_slug": {
            "type": "string"
          },
          "compensation_type": {
            "description": "`commission_only` when the job description states the role is paid\nentirely by commission, with no base salary (db/370, DQ rule v5: a\nfixed pattern match on the description text, checked by hand on a\n100-row judged sample at 98% precision before shipping). OMITTED\nwhen the rule found no such claim: this is NOT the same as \"has a\nbase salary\"; most postings simply do not say either way.\nInformational only: it NEVER hides a listing, and it can be wrong\nin rare cases, same as every other rule-derived field on this\nobject. Filterable with `?compensation_type=commission_only` and\nexcludable with `?exclude_compensation_type=commission_only`.\nfield_sources.compensation_type is always `inferred` when the key\nis present: this is never something a source publishes in a\nstructured field, only something read out of the advert text.\n",
            "enum": [
              "commission_only"
            ],
            "type": "string"
          },
          "content_changed_at": {
            "description": "When content_version last changed. For rows that existed on 9 Nov 2026 it starts at the older\nchange clock, which also moved on JOA's own repairs: it can be later than the employer's last\nchange, never earlier. Null exactly when content_version is.\n",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "content_version": {
            "description": "The employer content version (9 Nov 2026): an opaque string (today 12 hex characters) that changes\nonly when the employer changed what the posting says: title, description (whitespace ignored),\napply_url, employment_type, location text, a remote_type the source states and a salary the source\nstates. It never changes when JOA re-derives a field (city, region, country, countries, category,\nseniority, company) or repairs one. A copy that holds a different version should refetch the row;\nthe same version means the employer's text is unchanged. Compare for equality only. Null for a row\nthat has no version yet.\n",
            "type": [
              "string",
              "null"
            ]
          },
          "contract_category": {
            "description": "The contract kind the posting establishes (db/232): `permanent` is\nreturned only when the posting STATES an open-ended contract (CDI,\nunbefristet, tempo indeterminato, indefinido, ...); `fixed_term`\nends on a date or fixed period; `project_based` ends on completion\nof a defined project; `seasonal` when the source says seasonal;\n`apprenticeship` is a statutory work-and-study contract;\n`internship` includes traineeships; `other` is a STATED form none\nof these represent (zero-hours, casual, per diem, Minijob,\nWerkstudent, ...). An ARRAY (dual-option adverts), main option\nfirst. OMITTED when the posting states none (most postings);\nfilterable as `?contract_category=unknown`. For vendors the\ncategory only describes the term of the engagement.\n",
            "items": {
              "enum": [
                "permanent",
                "fixed_term",
                "project_based",
                "seasonal",
                "apprenticeship",
                "internship",
                "other"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "contract_category_confidence": {
            "description": "Present ONLY when field_sources.contract_category is `inferred`:\nthe measured precision of the rule, 0..1.\n",
            "type": "number"
          },
          "countries": {
            "description": "Added 8 Nov 2026. Every country the job is open to, ISO 3166-1 alpha-2 codes, `country`\nfirst when the job has one. A one-country job reads `[country]`; a role open to several,\nsuch as \"Remote (United States | Canada)\", lists them all in the order the source names\nthem (after `country`). Always present: `[]` when no country is known (where `country`\nitself is absent). Filter on it with `country_match=any`.\n",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "country": {
            "description": "ISO 3166-1 alpha-2 code of the job's country. Absent when no single country is\nestablished, which includes a remote role open to several countries with no first\nchoice (those list them in `countries`).\n",
            "type": "string"
          },
          "country_confidence": {
            "description": "Present ONLY when WE filled the country (`field_sources.country` is `inferred` after\na gazetteer-plus-model agreement, or `llm_inferred`). `high`: gazetteer and a language\nmodel agree. `low`: a language model alone read the location text (`llm_inferred`;\nmeasured precision about 95%, see field_sources.country). Omitted on every other row.\n",
            "enum": [
              "high",
              "low"
            ],
            "type": "string"
          },
          "description": {
            "description": "The full advert text. On a list, present ONLY when the request set include_description=true, and only on the 97.3% of rows that have one (2,376,694 live rows). On `GET /v1/jobs/{id}` it is always inside `data` when the row has one (since 2026-11-11), and the same value also sits beside `data` (kept for compatibility).\n\nPersonal email addresses are removed: an email address that identifies one person (a name-based address such as jane.doe@...) is replaced with `[personal contact removed]`. Company mailboxes stay in the text: role mailboxes (jobs@, careers@, hr@, info@ and their equivalents in other languages). Phone numbers are not changed on this path. A role an employer listed with us directly keeps its text exactly as the employer published it. Nothing else in the text, `apply_url` and every other field are unchanged. `description_length` counts the stored text, before this replacement. The bulk `GET /v1/export` removes every email address and phone number instead.\n\nOn rows of source `nhs_jobs` (NHS Jobs) the text is the short summary the NHS Jobs feed publishes (about 150 characters, cut by NHS Jobs and ending in \"...\"), followed by a line \"Salary: ...\" when the feed states one; it is not the full advert, which is at `apply_url`.\n",
            "type": "string"
          },
          "description_length": {
            "description": "Size of description in bytes. Always present: 0 means the row carries\nno advert text, exactly as has_description:false does. Computed with\noctet_length, which reads the length out of the TOAST header without\nfetching the text. The text itself still needs\ninclude_description=true.\n",
            "type": "number"
          },
          "description_truncated": {
            "description": "True while the stored advert text is known to be cut short at its\nsource: harvested under an old 4,000-character limit and not yet\nre-fetched, or longer than the 100,000-character safety ceiling.\nJOA does not shorten the text it serves; this flag says the\nledger's own copy is incomplete. Always present.\n",
            "type": "boolean"
          },
          "embedding": {
            "description": "Present ONLY with `include=embedding`. The document vector of this\njob; see the `include` parameter for the query prefix and the model.\n",
            "properties": {
              "dim": {
                "example": 1024,
                "type": "integer"
              },
              "model": {
                "example": "Qwen/Qwen3-Embedding-8B",
                "type": "string"
              },
              "normalized": {
                "description": "Unit L2 norm, so cosine similarity equals the dot product.",
                "type": "boolean"
              },
              "reason": {
                "description": "Present only when vector is null.",
                "enum": [
                  "no_vector",
                  "vectors_unavailable"
                ],
                "type": "string"
              },
              "vector": {
                "description": "dim float32 values, or null when the job has none (see reason).",
                "items": {
                  "format": "float",
                  "type": "number"
                },
                "type": [
                  "array",
                  "null"
                ]
              }
            },
            "required": [
              "model",
              "dim",
              "normalized",
              "vector"
            ],
            "type": "object"
          },
          "employer_website": {
            "description": "The employer's own site as THIS posting states it:\nhiringOrganization.url or sameAs, or the ATS's own field (db/144).\nA different claim from `website` on /v1/companies, which is verified\nagainst the domain's own page.\n",
            "type": "string"
          },
          "employment_type": {
            "description": "One of Full-time, Part-time, Contract, Temporary, Internship, or absent\n(present on 39.3% of served rows, 23 Oct 2026). A contract-duration word\nthe source gives without hours (Permanent, Regular, CDI, Employee) is not\nread as Full-time: such a row shows none. A row\nthat already carried one keeps it; otherwise this is the\nemploymentType the page itself declares (db/144), normalised to the\nsame five values (db/220; a declared value that maps to none of them\nis not shown). Either way the value is the source's own, which is\nwhy field_sources.employment_type is published whenever the key is\npresent, and ?employment_type= filters on exactly this value.\nUNCHANGED and frozen since the contract fields (engagement,\ncontract_category, agency, working_schedule) shipped: existing\nintegrations keep byte-identical behaviour. Rough old-to-new\nreading: Contract/Temporary mostly correspond to engagement=vendor\nor contract_category=fixed_term, Internship to\ncontract_category=internship, but the new fields come from what\nthe posting STATES, so they are populated independently, not\ntranslated from this one.\n",
            "type": "string"
          },
          "engagement": {
            "description": "The employment relationship the posting establishes (db/232, plan\nv2.1): `employee`: an employment contract with some employer of\nrecord running payroll (the advertiser, a temp agency or an\numbrella company); `vendor`: a commercial or civil-law service\nrelationship (freelance, B2B, 1099, C2C, Brazilian PJ: the person\ninvoices); `other`: a stated hybrid national form that everyday\nunderstanding puts on neither side (Polish umowa zlecenie /\numowa o dzieło, Italian co.co.co., Spanish TRADE, umbrella/portage\narrangements, statutory non-employment internships such as the\nFrench stage, volunteering). The raw national term is retained\ninternally. An ARRAY because some adverts offer two arrangements\n(\"CLT ou PJ\", \"UoP lub B2B\"): main option first, at most 3 values,\nusually exactly 1. OMITTED when the posting does not establish it,\nwhich is most postings; absence is filterable as\n`?engagement=unknown` and never means \"employee by default\".\n",
            "items": {
              "enum": [
                "employee",
                "vendor",
                "other"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "engagement_confidence": {
            "description": "Present ONLY when field_sources.engagement is `inferred`: the\nmeasured precision of the rule that established the value, 0..1. A\npublished value carries no confidence: it is the source's words.\n",
            "type": "number"
          },
          "esco_occupation_label": {
            "description": "English preferred label of the matched ESCO occupation. Present\nexactly when `esco_occupation_uri` is.\n",
            "type": "string"
          },
          "esco_occupation_uri": {
            "description": "URI of the ESCO occupation (ESCO v1.2.1, European Commission) whose\nPREFERRED label equals this job's title, after removing gender\nmarkers, bracketed text, a trailing segment after a dash, comma,\ncolon or bar, and seniority or contract words. Matched in the\nlanguage of the advert (and in English for adverts in other\nlanguages). Only an exact match to a preferred label that belongs to\nexactly one occupation is served; alternative labels, partial\nmatches and similarity are not used. OMITTED when there is no such\nmatch: absence means unknown, never \"no occupation\".\nThis is our automated inference, not the employer's classification.\nMeasured on 416 hand-checked postings: 92.8% the right occupation,\n97.1% the right occupation or a sibling inside the same ISCO unit\ngroup. About 6% of served postings carry it today. Provenance:\n`field_sources.occupation` is `inferred`. This service uses the\nESCO classification of the European Commission.\n",
            "type": "string"
          },
          "expires_at": {
            "description": "When the vacancy stops being valid, from either source: the timestamp\nthe radar PROVED it dead (upstream_expired_at), or the date the\nposting itself states (db/144, schema.org validThrough). A row that\nalready carried the first keeps it. PRESENT on a live row whenever\nthe posting states its own deadline — 14.2% of live rows on 5 Nov\n2026, and about 1% of those dates are already in the past while the\nsource still lists the role, so treat a past expires_at on a live\nrow as the source's claim, not ours. (Corrected 6 Nov 2026: this\nsaid \"absent while the vacancy is live\".) Same shape as every other\ntimestamp here: a date from the posting renders as midnight of that\ndate.\n",
            "type": "string"
          },
          "field_sources": {
            "$ref": "#/components/schemas/FieldSources"
          },
          "first_seen_at": {
            "description": "When the vacancy first entered this ledger. Populated on 100% of rows, unlike posted_at which the source often omits, so this is the field to sort or backfill by when you need every row to have a date.\n",
            "type": "string"
          },
          "has_description": {
            "type": "boolean"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "isco_code": {
            "description": "ISCO-08 unit group (4 digits) of the matched ESCO occupation; its\nfirst 1, 2 and 3 digits are the major, sub-major and minor group.\nPresent exactly when `esco_occupation_uri` is. Same inference\ncaveat as `esco_occupation_uri`.\n",
            "type": "string"
          },
          "language": {
            "description": "ISO 639-1 code of the advert text, detected automatically from the description (or the title when there is no description). null when the text is mixed, too short or the detection is not confident. Measured precision \u003e= 99% on a random sample; null does not mean English.\n",
            "type": [
              "string",
              "null"
            ]
          },
          "language_basis": {
            "description": "What evidence the detection used: \"text\" (the description), \"title\" (the advert text was missing or too short), \"title+country\" (the title is English, the advert text is missing or too short, and the job is in the US, GB, CA, AU, IE, NZ, SG or IN; measured precision 99.4% against description-based labels on 28,797 rows) or \"none\". null whenever language is null. field_sources.language reports \"detected\" when a value is published (our detection of the advert text, never the source's declaration).\n",
            "type": [
              "string",
              "null"
            ]
          },
          "language_confidence": {
            "description": "The detector's own confidence (0.00-1.00) for the published language; null whenever language is null. A label is stored only at \u003e=0.80 with a description and \u003e=0.90 title-only; labels with language_basis \"title+country\" carry a score between 0.50 and 0.85 (the title score, capped at 0.85), so they are always below the other bases.\n",
            "type": [
              "number",
              "null"
            ]
          },
          "last_verified_at": {
            "description": "The last time JOA positively confirmed this vacancy at its source: a request that found the posting live (its own page, or its record in the employer's ATS API), or the posting listed in a fresh read of the employer's own job list; if nothing is newer, the time it was first harvested from that source. For a role the employer pushes to JOA, the partner's last push or heartbeat. Nothing else moves it (not a rebuild of the ledger, not a timer). Same value everywhere: list, detail, export, changes, closed, MCP, and the verified_after filter.\n",
            "format": "date-time",
            "type": "string"
          },
          "last_verified_via": {
            "description": "Which kind of confirmation last_verified_at is. posting_page = the posting's own page was fetched (or rendered) and judged live; ats_api = the employer's ATS API returned this posting as live; board_api = Ashby's own job board (its system of record) listed this posting as live; source_list = the posting was listed in a fresh read (at most 3 hours old) of the employer's own job list; first_harvest = no confirmation newer than the harvest that first brought it in; partner_feed = a role the employer pushes to JOA; verifier = a verifier confirmation made before 23 Oct 2026 whose method was not recorded.\n\n`board_api` is a board-level read, not a check of the individual posting URL: JOA asks\nAshby's posting API for the employer's live board and finds the posting listed on it. It is\nAshby's own system of record, so the verdict counts as a page-level confirmation exactly as\nit did before this label existed (24 Oct 2026); the label exists so a buyer can tell a\nboard-level read from a posting-level check.\n",
            "enum": [
              "posting_page",
              "ats_api",
              "board_api",
              "source_list",
              "first_harvest",
              "partner_feed",
              "verifier"
            ],
            "type": "string"
          },
          "legal_note": {
            "description": "Added 11 Nov 2026. The text of the legal note named by `legal_note_code`, null exactly when the code\nis. For `immigration_information`: \"This information is not immigration advice, legal advice or any\nother service to candidates. It is provided for information only and may be incomplete, inaccurate\nor out of date. Before starting any immigration or employment process, contact a qualified, certified\nprofessional.\" Immigration and sponsor information is informational only. Show the legal_note with\nthis information, unless you are an authorised immigration adviser presenting it within your\nregulated service. If you omit it, you take full responsibility (Terms, \"Immigration and sponsor\ninformation\").\nFor `nhs_jobs_source`: \"These jobs come from NHS Jobs under the Open Government Licence v3.0. Review the\nTerms, section NHS Jobs: https://jobopportunitiesapi.org/terms#nhs-jobs\".\n",
            "type": [
              "string",
              "null"
            ]
          },
          "legal_note_code": {
            "description": "Added 11 Nov 2026. The code of the legal note that goes with this row, null when none applies.\nCodes: `immigration_information`, on every job whose `sponsor_registers` or `visa_checks` is not empty or whose `work_visa_text` carries a statement, and `nhs_jobs_source`, on every job from NHS Jobs\n(`source` `nhs_jobs`). When several notes apply, this key carries the FIRST in this order:\n`immigration_information`, then `nhs_jobs_source` (so the value never changed for a row that carried\nit before); `legal_notes` lists every note that applies. Codes are stable; `/v1/help` lists every note\n(`legal_notes`) with its text, version and effective date. Always present.\n",
            "type": [
              "string",
              "null"
            ]
          },
          "legal_notes": {
            "description": "Added 11 Nov 2026. Every legal note that applies to this row, in order (`immigration_information`\nfirst, then `nhs_jobs_source`), each with its `code` and `text`; `[]` when none applies. Always present.\n`legal_note_code` and `legal_note` carry the first entry, so a client that reads only them keeps working;\nread this list to show every note, for example on a job from NHS Jobs that also carries immigration\ninformation (both notes apply).\n",
            "items": {
              "properties": {
                "code": {
                  "enum": [
                    "immigration_information",
                    "nhs_jobs_source"
                  ],
                  "type": "string"
                },
                "text": {
                  "type": "string"
                }
              },
              "required": [
                "code",
                "text"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "location": {
            "type": "string"
          },
          "posted_at": {
            "description": "The publication date or timestamp the source states. Day precision is\ncommon: when posted_at_precision is \"date\" the source published a\ncalendar date with no time, and posted_at carries that date at a fixed\n12:00:00Z, so only the day is meaningful and the time part carries no\ninformation. To mirror \"new jobs since X\", use listed_after (the day\nJOA admitted the row to the served set), not posted_after: the\nemployer's own posted_at is often days older than the day JOA first\nsaw the row. Use posted_after only for the employer's stated\npublication window.\n",
            "type": "string"
          },
          "posted_at_precision": {
            "description": "Present only when the source publishes a calendar date and no time: Workday, and (since 23 Oct 2026) any row whose posted_at was taken from the date the posting page itself states (schema.org datePosted or the ATS's own published date, read by the verification sweep) because the harvested record carried none. posted_at then carries that date at a fixed 12:00:00Z, so the day is the same in every timezone from UTC-11 to UTC+11; the time part carries no information. Omitted when posted_at is a full timestamp.\n",
            "enum": [
              "date"
            ],
            "type": "string"
          },
          "provider_type": {
            "description": "The provider-level class, in the original vocabulary. Kept so a query written against it still resolves.",
            "enum": [
              "employer_ats",
              "government",
              "direct",
              "aggregator"
            ],
            "type": "string"
          },
          "region": {
            "description": "State, province or county where one could be established, on rows of\nANY country (corrected 6 Nov 2026: this said \"absent on every non-US\nrow\", which stopped being true as sources grew — in the 5 Nov audit\nsample 22.6% of rows carried one on DE, GB, FR, CH, NL, BR and\nothers, for example \"Bayern\" on a DE row). US rows carry the\ntwo-letter state code; other countries carry the subdivision the\nsource declared or the resolver established, usually as a name.\nAbsent on cities that resolve to more than one subdivision. db/078\nresolves it from the source's declared region first, then a state\nnamed in the free-text location, then an unambiguous city; db/144\nadds the region the page itself declares (schema.org addressRegion)\nwhere the listing column has none. field_sources.region reports\npublished whenever the row carries one and does not separate those\nderivations, so read it as \"we established a region\", not as a\nquotation.\n",
            "type": "string"
          },
          "relevance": {
            "description": "Present only on rows served with `sort=relevance`. `score` is an\nordering-only integer (comparable within one response, never\nacross queries); `tier` is the match class: exact, synonym,\nabbreviation or typo.\n",
            "properties": {
              "score": {
                "type": "integer"
              },
              "tier": {
                "enum": [
                  "exact",
                  "synonym",
                  "abbreviation",
                  "typo"
                ],
                "type": "string"
              }
            },
            "type": "object"
          },
          "remote": {
            "description": "- remote: The posting says the job is done fully from home or from anywhere, with no regular office attendance.\n- hybrid: The posting offers or requires a mix of office and remote work, for example 'remote possible', 'telework 2 days a week' or partial remote.\n- on_site: The job is done at the employer's location; the posting excludes remote work, mentions it only as occasional, or the role is hands-on (care, warehouse, driving).\n- not stated (null): The posting says nothing we can read about where the work is done.\n\nremote_inferred=true marks all of these as our reading of the text, not an employer field.\n",
            "enum": [
              "remote",
              "hybrid",
              "on_site"
            ],
            "type": "string"
          },
          "remote_inferred": {
            "description": "**Always present.** True when we derived `remote` rather than read\nit. It used to be omitted when false, which made a stated value and\nan absent one identical on the wire.\n",
            "type": "boolean"
          },
          "salary_currency": {
            "description": "ISO code, as the source states it. Same sources as salary_min. When the\nsource states the amount but never a currency and the posting's country\nhas exactly one whose magnitude fits, we fill it and\n`field_sources.salary_currency` reads `inferred`; otherwise it stays\nabsent. Never guessed across borders, never an estimate.\n",
            "type": "string"
          },
          "salary_max": {
            "description": "The top of the range, same sources as salary_min. Absent when the\nsource states a single figure or none at all.\n",
            "type": "number"
          },
          "salary_min": {
            "description": "The source's own figure. A row that already carried one keeps it;\notherwise this is the baseSalary the page declares, or the ATS's\nsalaryRange (db/144). Absent, not null, when there is no figure,\nwhich is the case for most employers.\n",
            "type": "number"
          },
          "salary_min_annual_eur": {
            "description": "salary_min converted to an annual EUR figure, so a row quoting USD/hour and one quoting GBP/year are comparable. NULL when the period or the currency is unrecognised, never guessed, because reading an hourly rate as a salary is wrong by a factor of 2080. Converted with the indicative rates in /v1/meta/freshness, not a settlement rate.\n",
            "type": "number"
          },
          "salary_period": {
            "description": "hour, day, week, month or year, as the source states it. Same sources\nas salary_min. When the source states the amount but never a period and\nthe magnitude allows exactly one reading for that country and currency,\nwe fill it and `field_sources.salary_period` reads `inferred`; otherwise\nit stays absent. The amounts are never changed and never estimated.\nFor jobs in the United Kingdom, Ireland, the Netherlands and Denmark, a\nsalary read from the advert page whose amount and period do not fit\ntogether (judged against the country's statutory minimum wage where\nthere is one, and fixed ceilings; for example a monthly salary labelled\nper week, or an hourly rate labelled per month) is withheld:\nsalary_min, salary_max, salary_currency and salary_period are all\nabsent. Where the advert states the unit next to the amount, that unit\nis used instead. A salary that reaches JOA another way (the source's own\njob feed, or our reading of the advert text) is not yet checked this way.\n",
            "type": "string"
          },
          "salary_source": {
            "description": "Where the figure came from. `structured` is a field the source itself published. `parsed_description` is a real figure quoted in the advert text that WE read out and normalised: we chose the number and the period, so `field_sources.salary` reports it as `inferred`, never `published`.\n\nThis marker describes the LISTING row only. A figure that arrived\nfrom the extracted side table (db/144) is the source's own baseSalary\nor salaryRange field, and `field_sources.salary` reports it as\n`published` while salary_source itself is absent.\n",
            "enum": [
              "structured",
              "parsed_description"
            ],
            "type": "string"
          },
          "seniority": {
            "type": "string"
          },
          "similarity": {
            "description": "Present only on rows served by /v1/jobs/similar: the cosine similarity of this job's vector to the\nquery vector (-1 to 1, higher is closer), rounded to 4 decimals. Comparable within one query.\n",
            "type": "number"
          },
          "slug": {
            "type": "string"
          },
          "source": {
            "description": "The provider id, e.g. greenhouse, company_site, workday. The full published list is /public/providers; eures, arbeitsagentur and france_travail were named here until 2026-08-15, when they became discovery-only and left that list.",
            "type": "string"
          },
          "source_requisition_id": {
            "description": "The identifier the SOURCE uses for this vacancy (an ATS job id, a\nWorkday requisition id, a schema.org identifier), so a support ticket\nor a buyer's own ATS lookup can quote it. Absent on every row the\nverify sweep has not extracted yet (db/144); joa.listings has no\ncolumn for it, which is why the payload carried it for 0% of rows\nbefore.\n",
            "type": "string"
          },
          "source_type": {
            "description": "Per-row provenance where the source has been classified per row,\notherwise the provider's class. Snapshot of the distribution on\n5 Aug 2026: ats 1,063,129, career_site 672,526, public_agency 320,727;\nthe current split by source class is in /public/coverage (sources).\n\nRESERVED VALUES: `aggregator` and `agency` are accepted by the filter\nbut currently match no rows. Every aggregator source is marked\nnon-redistributable, so that inventory never enters the ledger at\nall, and no provider is classified `agency` yet. Filtering on either\nreturns an empty page. That is the data, not a fault.\n",
            "enum": [
              "ats",
              "career_site",
              "public_agency",
              "aggregator",
              "agency",
              "unknown"
            ],
            "type": "string"
          },
          "sponsor_registers": {
            "description": "Added 10 Nov 2026. The official government sponsor or work permit registers the employer\nappears on in the job's own country, one object per register: a register is shown only when\nits country is the job's country, or one of the countries a multi-country role is open to\n(the `countries` field). A German job at an employer on the UK register reads `[]`.\nThe registers: the UK Home Office register of licensed sponsors,\nthe IND public register of recognised sponsors (NL), the US Department of Labor LCA and\nPERM disclosure data (certified filings), the Canadian positive LMIA employers list, and\nothers as they are published. It means \"appears on the official register as of\n`as_of`\", never \"will sponsor\": a register says an employer is licensed (or has filed),\nnot that this job offers sponsorship. Matched at employer level by name, town and domain;\na country is published only after a hand-checked sample reached 95% precision. Always\npresent: `[]` when the employer is on none of the published registers, and for a posting\nthat names another employer than the company it was collected under. A job with a non-empty\n`sponsor_registers` carries the `immigration_information` legal note (`legal_note_code`,\n`legal_note`): this is information only, not immigration or legal advice.\n",
            "items": {
              "properties": {
                "as_of": {
                  "description": "The register's own date: its publication date, or for filing data the newest certified decision.",
                  "format": "date",
                  "type": "string"
                },
                "country": {
                  "description": "ISO 3166-1 alpha-2 code of the register's country.",
                  "type": "string"
                },
                "kind": {
                  "description": "licensed: the employer holds the licence or recognition the register lists (UK\nsponsor licence, IND recognised sponsor, Danish fast-track certification).\nfiling_evidence: the register is a record of approved filings or permits (US LCA\nor PERM, a Canadian positive LMIA, Irish employment permits), evidence the\nemployer has hired through the route, not a licence.\n",
                  "enum": [
                    "licensed",
                    "filing_evidence"
                  ],
                  "type": "string"
                },
                "match_scope": {
                  "description": "exact_entity: the register entry fits the employer named on the job. group_company: the\nnames are the same but the employer's name carries another country or legal form than the\nregister entry (the employer is \"Merz Aesthetics GmbH\", the UK register lists \"Merz\nAesthetics UK Limited\"), so the entry is a company with the same name in that country\nand may not be the employer itself. The same rule as POST /v1/sponsors/lookup decides (added\n11 Nov 2026). Also group_company when the posting names another legal entity of the group (a\nWorkday \"Company:\" field) or the entry is a site entity (\"Standard Aero (San Antonio), Inc.\")\nand the job is in another place: then the entry is a company of the same group, not the employer.\nAlso group_company for a curated link (NL and DK, 11 Nov 2026): a register entity linked to an\nemployer known under another name (a parent, brand or sister company, \"Landal GreenParks B.V.\" for\nLandal); the register lists that legal entity, not the employer, and when JOA has not confirmed that\nit employs for the job the statement says so. Such an entry is shown but does not make the job match\nsponsor_register=.\n",
                  "enum": [
                    "exact_entity",
                    "group_company"
                  ],
                  "type": "string"
                },
                "matched_name": {
                  "description": "The employer name exactly as the register prints it.",
                  "type": "string"
                },
                "register": {
                  "description": "The register as its publisher names it.",
                  "type": "string"
                },
                "route": {
                  "description": "The route, visa class or stream the register names (e.g. Skilled Worker, H-1B, PERM), several joined with \"; \".",
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "source_url": {
                  "description": "The official page the register is published on.",
                  "format": "uri",
                  "type": "string"
                },
                "statement": {
                  "description": "One plain sentence that always names the register entry. For exact_entity, \"Rolls-Royce plc\" appears on the official register \"...\" as of 2026-11-09. For a group_company decided by the name, A company with the same name in the United Kingdom, \"Merz Aesthetics UK Limited\", appears on the official register \"...\" as of 2026-11-03. It may not be the employer named on this job. When the posting names another legal entity of the group, for a site entity and for a curated link, A company of the same group in ..., \"...\", appears on the official register \"...\" as of .... It is not the employer named on this job; for a curated link JOA has not confirmed, the last sentence reads JOA has not confirmed that it is the legal entity that employs for this job, with the reason.",
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "status": {
            "enum": [
              "live",
              "closed"
            ],
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "upstream_expired_at": {
            "description": "When the radar proved the vacancy dead, as opposed to when we removed it. Still the radar's column and nothing else; `expires_at` is the key that also carries the posting's own validThrough date.",
            "type": "string"
          },
          "verification_stale": {
            "description": "Present (true) only when last_verified_at is older than 18 hours. An honest label, never a removal.",
            "type": "boolean"
          },
          "visa_checks": {
            "description": "No check (visa_checks []) for a recruitment agency advert (agency is set) or when the title names a country other than the job's country (English, Dutch, German and Danish country names).\nAdded 11 Nov 2026. Visa information for a job in the United Kingdom (GB), Ireland (IE), the Netherlands\n(NL) or Denmark (DK): one object with two factual checks of the advert against the official published\nrules of the country's main work route, each with its sources and dates. `occupation_check` says\nwhether the occupation is on the official list of the route; `salary_check` says how the advertised pay\ncompares with the official thresholds. They describe facts and sources only. They are not advice and\nnot a decision on any person's case: whether a visa or permit is granted depends on the person, the\nemployer and the authority, which an advert does not show. The facts are the same for every reader.\nComputed daily by JOA from the advert (title, the published salary and its period) and the rules\nlisted in `sources`; `checked_on` is the day, `rules_version` the rule set. An occupation code is\nused only when the advert title exactly matches an entry of the ONS SOC 2020 coding index (UK and\nIreland) or JOA's ISCO-08 code for the title (Denmark); otherwise the occupation check is\n`occupation_unknown`. Irish checks are shown only while JOA's daily check finds the DETE occupation\nlists unchanged. Always present: `[]` for jobs in other countries, for a job not checked yet, and when\nthe field is switched off. Does not change `sponsor_registers`, filters or metering. A job with a\nnon-empty `visa_checks` carries the `immigration_information` legal note (`legal_note_code`,\n`legal_note`).\n",
            "items": {
              "properties": {
                "checked_on": {
                  "description": "The day JOA computed the check.",
                  "format": "date",
                  "type": "string"
                },
                "country": {
                  "description": "The country whose rules were compared (the job's country).",
                  "enum": [
                    "GB",
                    "IE",
                    "NL",
                    "DK"
                  ],
                  "type": "string"
                },
                "legal_note_code": {
                  "enum": [
                    "immigration_information"
                  ],
                  "type": "string"
                },
                "occupation_check": {
                  "properties": {
                    "conditions": {
                      "description": "Conditions of the listing that an advert does not show.",
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    },
                    "occupation_code": {
                      "description": "The occupation code used, null when none was assigned.",
                      "properties": {
                        "alternatives": {
                          "description": "Other codes the same title maps to.",
                          "items": {
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "code": {
                          "type": "string"
                        },
                        "method": {
                          "description": "How the code was assigned.",
                          "type": "string"
                        },
                        "system": {
                          "enum": [
                            "SOC 2020",
                            "SOC 2010",
                            "ISCO-08"
                          ],
                          "type": "string"
                        }
                      },
                      "type": [
                        "object",
                        "null"
                      ]
                    },
                    "sources": {
                      "items": {
                        "$ref": "#/components/schemas/VisaCheckSource"
                      },
                      "type": "array"
                    },
                    "statement": {
                      "description": "One or more plain sentences with the code, the list and the rules date.",
                      "type": "string"
                    },
                    "status": {
                      "description": "on_skilled_list: the occupation code is on the official list of the route (GB Tables 1 to 3, the\nImmigration Salary List or the Temporary Shortage List; IE the Critical Skills Occupations List;\nDK a Positive List entry that the advert title matches). on_list_in_country_only (GB): listed only\nfor applications made inside the UK (care workers, SW 6.1B). on_list_transitional_only (GB): listed\nonly for people who already held Skilled Worker permission under earlier rules. not_on_skilled_list:\nnot on the list (GB Table 6 or no table; IE not on the Critical Skills list, the statement says\nwhether it is on the Ineligible List of Occupations; DK not on a Positive List). occupation_unknown:\nno occupation code could be assigned, or candidate codes give different results. not_assessed\n(NL): the route has no occupation list.\n",
                      "enum": [
                        "on_skilled_list",
                        "on_list_in_country_only",
                        "on_list_transitional_only",
                        "not_on_skilled_list",
                        "occupation_unknown",
                        "not_assessed"
                      ],
                      "type": "string"
                    }
                  },
                  "type": "object"
                },
                "route": {
                  "description": "The route whose published rules were compared, e.g. Skilled Worker.",
                  "type": "string"
                },
                "rules_as_of": {
                  "description": "The date of the main rule document (GB Appendix Skilled Worker, IE list documents, DK Positive Lists, NL amounts).",
                  "type": "string"
                },
                "rules_version": {
                  "description": "The version of the rule set the check used.",
                  "type": "string"
                },
                "salary_check": {
                  "properties": {
                    "applicant_case": {
                      "description": "GB only: the category of applicant the UK rules define that the status refers to (the first one for which the code is listed). The same for every reader.",
                      "enum": [
                        "first_sw_from_outside_uk",
                        "first_sw_in_uk",
                        "sw_since_before_22jul2025",
                        "sw_since_before_4apr2024",
                        null
                      ],
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "conditions": {
                      "description": "Conditions an advert does not show (employer, person, hours, quotas).",
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    },
                    "flags": {
                      "items": {
                        "enum": [
                          "hours_assumed_37_5",
                          "below_national_living_wage"
                        ],
                        "type": "string"
                      },
                      "type": "array"
                    },
                    "reason": {
                      "description": "Why the status is what it is, null when no reason is needed. occupation_not_listed: no threshold\napplies to the code (GB Table 6 codes always). occupation_on_dete_excluded_list: the code is on the\nIrish Ineligible List of Occupations. DETE states that permits are not issued for these employments\nirrespective of remuneration, subject to the exceptions the statement quotes.\nbelow_national_living_wage (GB) and below_minimum_hourly_rate (IE): the hourly pay is below the\nlegal or permit minimum. pay_period_doubtful: the yearly figure is so low (under GBP 10,000,\nEUR 10,000 or DKK 75,000) that the stored pay period is probably wrong, so the pay is not compared.\npay_period_implausible: the amount does not fit its stated period (for example an hourly\nfigure labelled monthly): below a full-time year at the statutory minimum wage, or above five\ntimes the general threshold of the route (ten times for a stated year), so the pay period is\nprobably wrong and the pay is not compared. pay_period_not_supported: weekly or daily pay is not\ncompared (a stated week or day is too often a monthly or hourly figure). pay_source_unverified:\nthe pay comes from the page's structured data, whose pay period JOA does not yet verify, so it is\nnot compared.\n",
                      "enum": [
                        "no_salary",
                        "currency_not_gbp",
                        "currency_not_eur",
                        "currency_not_dkk",
                        "no_pay_period",
                        "day_rate_without_days_and_hours",
                        "hours_not_stated",
                        "range_spans_threshold",
                        "occupation_unknown",
                        "occupation_not_listed",
                        "occupation_code_uncertain",
                        "pay_scale_band_not_stated",
                        "below_national_living_wage",
                        "below_minimum_hourly_rate",
                        "occupation_on_dete_excluded_list",
                        "amounts_not_archived_for_date",
                        "holiday_allowance_unclear",
                        "weekly_hours_below_30",
                        "pay_period_doubtful",
                        "pay_period_implausible",
                        "pay_period_not_supported",
                        "pay_source_unverified",
                        null
                      ],
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "sources": {
                      "items": {
                        "$ref": "#/components/schemas/VisaCheckSource"
                      },
                      "type": "array"
                    },
                    "statement": {
                      "description": "Plain sentences with the figures compared, the thresholds and what counts as pay.",
                      "type": "string"
                    },
                    "status": {
                      "description": "at_or_above_general_threshold: the advertised pay is at or above the general threshold of the\nroute. at_or_above_reduced_threshold_only: below the general threshold, at or above a reduced\nthreshold that depends on the person or the job (for example a new entrant or an age band).\nbelow_published_thresholds: below every published threshold. salary_not_comparable: the pay\ncannot be compared, `reason` says why.\n",
                      "enum": [
                        "at_or_above_general_threshold",
                        "at_or_above_reduced_threshold_only",
                        "below_published_thresholds",
                        "salary_not_comparable"
                      ],
                      "type": "string"
                    },
                    "threshold": {
                      "description": "The threshold the status refers to, in threshold_currency per threshold_period.",
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "threshold_currency": {
                      "enum": [
                        "GBP",
                        "EUR",
                        "DKK"
                      ],
                      "type": "string"
                    },
                    "threshold_period": {
                      "description": "year, or month for NL (the IND amounts are gross a month).",
                      "enum": [
                        "year",
                        "month"
                      ],
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "work_visa_text": {
            "description": "What the advert itself says about visa sponsorship, work permits, relocation and the\nright to work: `statements`, each with a code and a quote copied word for word from the employer's\nadvert, and an `evidence_level` given by a fixed rule over the codes. It describes the advert:\nnot advice and not a decision on any person's case. It says nothing about whether a visa or permit is\ngranted, which depends on the person, the employer and the authority. The quotes are the employer's own\nwords in the advert's language, never translated or corrected; the codes are JOA's reading of them (a\nlanguage model finds and codes the statements, and code checks that every quote is found exactly in the\nadvert). Silence is the normal case: most adverts say nothing of this kind, also at employers that hire\nfrom abroad, so `no_information` means the advert is silent, not that the employer refuses. The\ncountries read so far and the date are in `/v1/help` (`work_visa_text.coverage`); every other job reads\n`not_assessed`. Always present. Does not change `sponsor_registers`, `visa_checks` or metering. A job\nwhose `work_visa_text` carries a statement carries the `immigration_information` legal note\n(`legal_note_code`, `legal_note`). Filter with `visa_text`.\n",
            "properties": {
              "as_of": {
                "description": "The day (UTC) the advert was read. Null with not_assessed.",
                "format": "date",
                "type": [
                  "string",
                  "null"
                ]
              },
              "evidence_level": {
                "description": "stated_closed: at least one statement is text_no_sponsorship, text_permit_required or\ntext_citizenship_restriction; this wins over every other statement of the advert. stated_open: a\nstatement is text_permit_support and no closing statement exists. no_information: JOA read the\nadvert and found no such statement, or only text_relocation_support. not_assessed: no current\nreading, because the job was not read yet, or its title or text changed since it was read (JOA\ncompares a hash of the exact text that was read, byte for byte; a change of any other field does not\ncount), or a quote cannot be shown exactly as the employer wrote it, or the field is switched off.\nAdverts longer than 8,000 characters are read as their first 5,000 and last 3,000 characters.\n",
                "enum": [
                  "stated_open",
                  "stated_closed",
                  "no_information",
                  "not_assessed"
                ],
                "type": "string"
              },
              "legal_note_code": {
                "description": "immigration_information when the field carries a statement, null otherwise.",
                "enum": [
                  "immigration_information",
                  null
                ],
                "type": [
                  "string",
                  "null"
                ]
              },
              "method_version": {
                "description": "The reading method, for example eu-signals-v1. Null with not_assessed.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "statements": {
                "description": "The statements found, [] when none (always [] with not_assessed).",
                "items": {
                  "properties": {
                    "code": {
                      "description": "text_permit_support: the advert says the employer helps with or pays for a visa, a work or\nresidence permit, an EU Blue Card or the immigration process for this job.\ntext_relocation_support: the advert offers help to relocate (a relocation package, moving costs,\nhelp to find housing, a relocation bonus or service); on its own it says nothing about permits.\ntext_permit_required: the advert asks for an existing right to work in the country (a valid work\nor residence permit, a named permit type, settled status), or says the employer does not help\ncandidates who need one. text_no_sponsorship: the advert says the employer does not or cannot\nsponsor visas or work permits. text_citizenship_restriction: the advert limits the job to\ncitizens or nationals of a country, or of the EU or EEA, or asks for a security clearance that\nneeds citizenship.\n",
                      "enum": [
                        "text_permit_support",
                        "text_relocation_support",
                        "text_permit_required",
                        "text_no_sponsorship",
                        "text_citizenship_restriction"
                      ],
                      "type": "string"
                    },
                    "method": {
                      "description": "The statement is in the employer's own advert.",
                      "enum": [
                        "published_by_employer"
                      ],
                      "type": "string"
                    },
                    "quote": {
                      "description": "The employer's own words, copied character for character from the advert title or description, in the original language. Never translated, shortened or corrected. A statement is shown only with its quote.",
                      "type": "string"
                    },
                    "quote_lang": {
                      "description": "ISO 639-1 code of the language of the quote: the language JOA detected for the advert text (the job's `language`), null when not detected.",
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "code",
                    "quote",
                    "quote_lang",
                    "method"
                  ],
                  "type": "object"
                },
                "type": "array"
              }
            },
            "required": [
              "evidence_level",
              "statements",
              "method_version",
              "as_of",
              "legal_note_code"
            ],
            "type": "object"
          },
          "working_schedule": {
            "description": "The stated schedule. `flexible` covers adverts offering either\nschedule. OMITTED when not established\n(`?working_schedule=unknown`). Distinct from, and independent of,\nthe frozen employment_type field above.\n",
            "enum": [
              "full_time",
              "part_time",
              "flexible"
            ],
            "type": "string"
          },
          "working_schedule_confidence": {
            "description": "Present ONLY when field_sources.working_schedule is `inferred`.\n",
            "type": "number"
          }
        },
        "required": [
          "id",
          "slug",
          "title",
          "company",
          "company_slug",
          "remote_inferred",
          "last_verified_at",
          "last_verified_via",
          "status",
          "source",
          "source_type",
          "provider_type",
          "has_description",
          "field_sources"
        ],
        "type": "object"
      },
      "JobPage": {
        "properties": {
          "completeness": {
            "description": "Present only when you passed `require_fields`. Every row in `data`\ncarries all of `required` as `published` in `field_sources`.\n\n`published_in_ledger` is per field and ledger-wide. The number\nmatching your other filters as well is at most the smallest of them.\nIt is deliberately not an exact count of your query: that is an\naggregate over the whole ledger, and running one per request is how\nan endpoint becomes a timeout. `by_country` links to the per-country\ntable, which is where \"is there enough of this in my market\" is\nactually answered.\n",
            "properties": {
              "by_country": {
                "format": "uri",
                "type": "string"
              },
              "generated_at": {
                "format": "date-time",
                "type": "string"
              },
              "labels": {
                "additionalProperties": {
                  "type": "string"
                },
                "type": "object"
              },
              "note": {
                "type": "string"
              },
              "published_in_ledger": {
                "additionalProperties": {
                  "type": "integer"
                },
                "type": "object"
              },
              "required": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            },
            "type": "object"
          },
          "data": {
            "items": {
              "$ref": "#/components/schemas/Job"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "hints": {
            "description": "Present only on an empty first page of a live search made with a key (12 Nov 2026): why nothing\nmatched, one finding per item, in plain sentences. Never on a page with rows, a later page, a `since`\npoll, `status=closed` or `any`, or the keyless website routes; every other answer keeps its exact\nbytes. Each item says only what one quick check found at that moment. A check that fails or takes\nlonger than 50 ms is left out, so the array can be absent even when a reason exists; a hint never\nturns the answer into an error. Read `reason` (stable codes), show `text` (it may change wording).\n",
            "items": {
              "$ref": "#/components/schemas/SearchHint"
            },
            "type": "array"
          },
          "location_ambiguous": {
            "description": "Present only when the request carried `?city=` (any value, including one\nwe cannot match). True when the rows the query matched sit in more than\none known country; rows with no country do not count as a second one.\nFalse when they do not, so an empty match answers false rather than\ngoing quiet. A request without `?city=` omits the key.\n",
            "type": "boolean"
          },
          "location_countries": {
            "description": "Present only when the request carried `?city=` (any value, including one\nwe cannot match). The country breakdown of the whole matched set, never\nof this page: buckets largest first, the unknown bucket last. `country`\nis an explicit null where the rows' country is unknown, never a missing\nproperty, and an empty match answers an empty array. A request without\n`?city=` omits the key.\n",
            "items": {
              "properties": {
                "count": {
                  "type": "integer"
                },
                "country": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          },
          "next_since": {
            "description": "Present only when the request carried `since` (9 Nov 2026): the token to send as `since` on your\nnext poll, the same on every page of the walk. Opaque: store it and send it back unchanged.\n",
            "type": "string"
          },
          "total_estimate": {
            "description": "Present only with `include_total=true`: how many rows match the\nfilters (never the cursor; the number is page-independent). Exact\nup to 10,000; 10,001 means \"more than 10,000\". Omitted when the\ncount did not finish in its time budget (see total_estimate_status).\n",
            "type": "integer"
          },
          "total_estimate_status": {
            "description": "Present only with `include_total=true`. `exact`: total_estimate is\nthe exact count. `at_least`: more than 10,000 rows match.\n`timed_out`: counting took longer than 4 seconds, so total_estimate\nis omitted; the page itself is complete and correct. A slow count\nnever fails the request.\n",
            "enum": [
              "exact",
              "at_least",
              "timed_out"
            ],
            "type": "string"
          }
        },
        "required": [
          "data",
          "next_cursor",
          "has_more"
        ],
        "type": "object"
      },
      "JobStatus": {
        "properties": {
          "closed_at": {
            "format": "date-time",
            "type": "string"
          },
          "closed_reason": {
            "type": "string"
          },
          "content_changed_at": {
            "format": "date-time",
            "type": "string"
          },
          "content_version": {
            "description": "See Job.content_version. Absent when the row has no version.",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "last_verified_at": {
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "enum": [
              "live",
              "closed",
              "withdrawn",
              "unknown"
            ],
            "type": "string"
          },
          "withdrawn_at": {
            "format": "date-time",
            "type": "string"
          },
          "withdrawn_reason": {
            "$ref": "#/components/schemas/WithdrawnReason"
          }
        },
        "required": [
          "id",
          "status"
        ],
        "type": "object"
      },
      "LimitError": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Error"
          },
          {
            "properties": {
              "docs_url": {
                "description": "The documentation section on this limit.",
                "format": "uri",
                "type": "string"
              },
              "limit": {
                "description": "The limit that was hit, in the unit of `window` (records per month, requests per day or per minute).",
                "format": "int64",
                "type": "integer"
              },
              "plan": {
                "description": "The key's plan, e.g. `explore`.",
                "type": "string"
              },
              "resets_at": {
                "description": "The exact reset instant, RFC 3339, always UTC.",
                "example": "2026-11-01T00:00:00Z",
                "format": "date-time",
                "type": "string"
              },
              "resets_at_text": {
                "description": "The same instant in plain English, UTC.",
                "example": "1 November 2026 at 00:00 UTC",
                "type": "string"
              },
              "upgrade": {
                "description": "Added 11 Nov 2026, on a 402 only, when a plan can lift the limit. Why these plans and the plans themselves,\ncheapest covering plan first. Prices come from the same catalogue as https://jobopportunitiesapi.org/pricing.\n",
                "properties": {
                  "by_hand": {
                    "description": "Added 12 Nov 2026. True when this key's subscription started at the Black Friday price: a move to the\noptions is set up by hand by support (write to support@jobopportunitiesapi.org), so the options carry no\ncheckout_url and the body no upgrade_url. Absent otherwise.\n",
                    "type": "boolean"
                  },
                  "demand": {
                    "description": "What the account asked for over the last `window_days` UTC days, every key of the account together:\n`records_delivered` (records charged, at least the current month's meter) plus `records_refused` (for every\nrefused call, its `limit`, 25 when absent, at most 200; 1 for a single job). The refused part reads the\nrequest log, which keeps 14 days, so it is a floor.\n",
                    "properties": {
                      "records": {
                        "description": "records_delivered plus records_refused.",
                        "format": "int64",
                        "type": "integer"
                      },
                      "records_delivered": {
                        "format": "int64",
                        "type": "integer"
                      },
                      "records_refused": {
                        "format": "int64",
                        "type": "integer"
                      },
                      "refused_calls": {
                        "format": "int64",
                        "type": "integer"
                      },
                      "window_days": {
                        "example": 30,
                        "type": "integer"
                      }
                    },
                    "type": "object"
                  },
                  "options": {
                    "description": "One or two plans. The first covers `demand.records` when any plan does; the second is the next plan up.",
                    "items": {
                      "properties": {
                        "checkout_url": {
                          "format": "uri",
                          "type": "string"
                        },
                        "covers_demand": {
                          "type": "boolean"
                        },
                        "currency": {
                          "example": "EUR",
                          "type": "string"
                        },
                        "interval": {
                          "enum": [
                            "month"
                          ],
                          "type": "string"
                        },
                        "name": {
                          "example": "Starter",
                          "type": "string"
                        },
                        "offer": {
                          "description": "Added 12 Nov 2026. A published price offer for this plan, present only while it runs and only on an\noption whose checkout_url starts a new checkout for this key (the code is applied there, nothing to\ntype). Today: the Black Friday deal, Starter monthly at half price for as long as the plan is kept, until ends_at.\n",
                          "properties": {
                            "code": {
                              "example": "BLACKFRIDAY",
                              "type": "string"
                            },
                            "ends_at": {
                              "format": "date-time",
                              "type": "string"
                            },
                            "name": {
                              "example": "Black Friday deal",
                              "type": "string"
                            },
                            "percent": {
                              "example": 50,
                              "type": "integer"
                            },
                            "price_cents": {
                              "example": 1450,
                              "type": "integer"
                            },
                            "price_text": {
                              "example": "€14.50 / month",
                              "type": "string"
                            },
                            "recurring": {
                              "description": "True when the price holds every month until the customer cancels.",
                              "type": "boolean"
                            },
                            "regular_price_cents": {
                              "example": 2900,
                              "type": "integer"
                            },
                            "regular_price_text": {
                              "example": "€29",
                              "type": "string"
                            }
                          },
                          "type": "object"
                        },
                        "one_click": {
                          "description": "True when checkout_url is the signed same-key one-click link.",
                          "type": "boolean"
                        },
                        "plan": {
                          "example": "starter",
                          "type": "string"
                        },
                        "price_cents": {
                          "example": 2900,
                          "type": "integer"
                        },
                        "price_text": {
                          "example": "€29 / month",
                          "type": "string"
                        },
                        "records_per_month": {
                          "example": 10000,
                          "format": "int64",
                          "type": "integer"
                        },
                        "vat": {
                          "example": "excl. VAT",
                          "type": "string"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array"
                  }
                },
                "type": "object"
              },
              "upgrade_plan": {
                "description": "The plan `upgrade_url` moves the key to. On a 402 it is `upgrade.options[0].plan`: the smallest plan that covers\nthe account's demand of the last 30 days (Starter for most free keys; since 11 Nov 2026, before that it was always\n`growth` for a free key). On a 429 it is the next plan up. Absent for the top plan and for marketplace keys.\n",
                "example": "starter",
                "type": "string"
              },
              "upgrade_url": {
                "description": "On a 402 for a free (Explore) key or a live trial: a one-click link for the SAME key\n(`https://jobopportunitiesapi.org/upgrade?k=\u003csigned token\u003e`). Opening it, no sign-in needed, redirects to a\npersonal Creem checkout that upgrades this key to `upgrade_plan` monthly; same secret, nothing to change in the\nintegration. The token is signed, scoped to the key and valid for 48 hours. For any other key it is a same-key\ncheckout link for `upgrade_plan` (the signed-in owner of the key completes it). Always equal to\n`upgrade.options[0].checkout_url` on a 402.\n",
                "format": "uri",
                "type": "string"
              },
              "used": {
                "description": "Usage in that window when the limit was hit.",
                "format": "int64",
                "type": "integer"
              },
              "window": {
                "description": "Which limit was hit. `calendar_month_utc` resets on the 1st of the next month at 00:00 UTC; `day_utc` at the next 00:00 UTC; `minute` at the next minute boundary.",
                "enum": [
                  "calendar_month_utc",
                  "day_utc",
                  "minute"
                ],
                "type": "string"
              }
            },
            "type": "object"
          }
        ],
        "description": "The body of a 402 `record_quota_exhausted` and a 429 `rate_limited`. `error`, `message` and `docs` are the same envelope as every other error; the remaining fields are optional additions. Marketplace channel keys and keys with no higher plan get the reset time but no `upgrade_*` fields.\n"
      },
      "SearchHint": {
        "description": "One finding about an empty /v1/jobs search (JobPage.hints).",
        "properties": {
          "live_jobs": {
            "description": "With `location_has_jobs` and `location_empty`, the live jobs of the location alone, counted up to 101 (101 means more than 100).",
            "example": 37,
            "type": "integer"
          },
          "param": {
            "description": "The request parameter the finding is about, e.g. `country`, `city`, `company_domain`, `q`, `posted_after`.",
            "example": "city",
            "type": "string"
          },
          "reason": {
            "description": "`country_not_covered`: no live job at all has this country. `company_domain_unknown`: no company in our\ndata has this website. `location_has_jobs`: the location parameters alone (city, country, state,\nregion) match live jobs, and the other parameters removed them all; `live_jobs` says how many.\n`location_empty`: the location parameters alone match no live job. `date_window_narrow`: a\nposted_after, verified_after or listed_after of 7 days or less. `city_unknown`: no live job has a\ncity of that name. `word_not_indexed`: a word of `q` is not in the search index.\n",
            "enum": [
              "country_not_covered",
              "company_domain_unknown",
              "location_has_jobs",
              "location_empty",
              "date_window_narrow",
              "city_unknown",
              "word_not_indexed"
            ],
            "type": "string"
          },
          "text": {
            "description": "One plain sentence for a person.",
            "example": "We have 37 live jobs in Newry (GB). None of them also matches your other filters.",
            "type": "string"
          },
          "value": {
            "description": "The value of that parameter as it was read.",
            "example": "Newry",
            "type": "string"
          }
        },
        "required": [
          "param",
          "reason",
          "text"
        ],
        "type": "object"
      },
      "SimilarPage": {
        "properties": {
          "completeness": {
            "type": "object"
          },
          "count": {
            "type": "integer"
          },
          "data": {
            "description": "Most similar first. Every row carries `similarity`.",
            "items": {
              "$ref": "#/components/schemas/Job"
            },
            "type": "array"
          },
          "model": {
            "example": "Qwen/Qwen3-Embedding-8B",
            "type": "string"
          },
          "query": {
            "properties": {
              "job_id": {
                "format": "uuid",
                "type": "string"
              },
              "type": {
                "enum": [
                  "job_id",
                  "vector"
                ],
                "type": "string"
              }
            },
            "type": "object"
          },
          "search": {
            "properties": {
              "candidates_checked": {
                "type": "integer"
              },
              "complete": {
                "description": "false when the filter matched many jobs but few of the nearest ones, so fewer than limit came back.",
                "type": "boolean"
              },
              "strategy": {
                "enum": [
                  "nearest_then_filter",
                  "exact_within_filter"
                ],
                "type": "string"
              }
            },
            "type": "object"
          }
        },
        "required": [
          "data",
          "count",
          "query",
          "model",
          "search"
        ],
        "type": "object"
      },
      "SponsorHit": {
        "properties": {
          "ambiguous": {
            "type": "boolean"
          },
          "ambiguous_reason": {
            "enum": [
              "several_legal_entities",
              "trading_name_only",
              "short_name",
              "unconfirmed"
            ],
            "type": "string"
          },
          "as_of": {
            "description": "The newest date of this organisation's entries on the register (the register's own date).",
            "format": "date",
            "type": "string"
          },
          "confidence": {
            "description": "0.97 name_town, 0.95 name_region, 0.92 name_country, 0.75 name_country_weak; null on an ambiguous candidate.",
            "type": [
              "number",
              "null"
            ]
          },
          "country": {
            "type": "string"
          },
          "filing_count": {
            "description": "Filings or permits counted on a filing-evidence register.",
            "type": "integer"
          },
          "kind": {
            "description": "licensed is a sponsor licence or recognition; filing_evidence is a published filing or permit, not a licence.",
            "enum": [
              "licensed",
              "filing_evidence"
            ],
            "type": "string"
          },
          "legal_name": {
            "type": "string"
          },
          "location_count": {
            "type": "integer"
          },
          "locations": {
            "description": "Up to 10 towns and regions of this organisation on the register; yours first when it matched.",
            "items": {
              "properties": {
                "region": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "town": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "match_method": {
            "enum": [
              "name_town",
              "name_region",
              "name_country",
              "name_country_weak",
              "name_only"
            ],
            "type": "string"
          },
          "match_type": {
            "description": "exact_legal_name means the name sent is the printed legal name word for word (case, accents, punctuation, brackets, \"and\" and \"the\" aside; Ltd is Limited). Accept these without a check. exact_normalised means the names are equal once legal forms and the words Group, Holding(s), International, Co, Company, UK and country words at the end, and text in brackets, are set aside (a name sent without its legal form, a trading name, an entry printed without a form). It is a match on a brand name; show legal_name or check it before you publish a claim. There is no fuzzy matching.",
            "enum": [
              "exact_legal_name",
              "exact_normalised"
            ],
            "type": "string"
          },
          "matched_on": {
            "description": "Which register name your name matched, the entry's legal name, a trading name the register prints (\"t/a\", \"d/b/a\"), or alias (NL only, an English name of a Dutch institution from JOA's curated table, mapped to the official Dutch name on the register).",
            "enum": [
              "legal_name",
              "trading_name",
              "alias"
            ],
            "type": "string"
          },
          "org_id": {
            "description": "The organisation number the register prints (KvK, CVR, FEIN), when it prints one.",
            "type": [
              "string",
              "null"
            ]
          },
          "org_id_type": {
            "enum": [
              "kvk",
              "cvr",
              "fein",
              null
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "publisher": {
            "type": "string"
          },
          "ratings": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "register": {
            "type": "string"
          },
          "register_code": {
            "enum": [
              "gb_ukvi_workers",
              "nl_ind_work",
              "dk_siri_fasttrack",
              "us_dol_lca",
              "us_dol_perm",
              "ca_esdc_lmia",
              "ie_dete_permits"
            ],
            "type": "string"
          },
          "register_file_date": {
            "description": "The date of the register file JOA loaded.",
            "format": "date",
            "type": [
              "string",
              "null"
            ]
          },
          "routes": {
            "description": "Route, programme or stream as the register prints it (Skilled Worker, H-1B, High Wage, ...).",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "source_url": {
            "format": "uri",
            "type": "string"
          },
          "statement": {
            "description": "One sentence that names the entry, for example: \"Rolls-Royce plc\" appears on the official register \"Register of licensed sponsors: workers\" (UK Home Office) as of 2026-11-09. Never a promise to sponsor.",
            "type": "string"
          },
          "trading_name": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "SponsorLookupInput": {
        "additionalProperties": false,
        "properties": {
          "country": {
            "description": "ISO 3166 alpha-2 (UK is read as GB). Omit to read every register.",
            "type": "string"
          },
          "name": {
            "maxLength": 300,
            "type": "string"
          },
          "region": {
            "description": "US state, two letters or in full. Only the US registers print a region; it is ignored for every other country. A US region that is not a state is not compared and hint says so.",
            "maxLength": 100,
            "type": "string"
          },
          "town": {
            "maxLength": 100,
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "SponsorLookupResult": {
        "properties": {
          "hint": {
            "description": "One plain sentence on what to send to get a single answer, for example \"Several register entries share this name. Add the town to get a single match, or send the full legal name, with its legal form, of the company you mean (see hits).\" Present on ambiguous, on not_found for a name of another country, on excluded short names and franchise brands, and on invalid and error (what is wrong, or to send that employer again on its own). Advice only, never a match.",
            "type": "string"
          },
          "hits": {
            "items": {
              "$ref": "#/components/schemas/SponsorHit"
            },
            "type": "array"
          },
          "hits_truncated": {
            "type": "boolean"
          },
          "input": {
            "$ref": "#/components/schemas/SponsorLookupInput"
          },
          "matched": {
            "description": "True when at least one hit is unambiguous.",
            "type": "boolean"
          },
          "possible_names": {
            "description": "On ambiguous, on not_found for a name of another country, and on a franchise brand exclusion. Up to 5 register legal names that are NOT matches, in this order. An entry with a similar name of another country or with a foreign legal form; a twin (the same name with or without Group, Holdings, International, UK or a country word, or with another legal form); names that contain the name sent as whole words, anywhere, a name that starts with it first (\"Arup\" finds \"Ove Arup and Partners International Ltd\"). Send the one you mean as the name to check it.",
            "items": {
              "properties": {
                "country": {
                  "type": "string"
                },
                "legal_name": {
                  "type": "string"
                },
                "region": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "register_code": {
                  "type": "string"
                },
                "town": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "reason": {
            "description": "On excluded (franchise_brand, staffing_or_recruiter, name_too_short), no_register, invalid (missing_name, bad_name, bad_country, bad_place, bad_body) and error (lookup_failed).",
            "type": "string"
          },
          "status": {
            "description": "matched means JOA found the register entry that is this employer by its name. ambiguous means a register entry has this name, or contains it as whole words, or differs from it only by a legal form or by a word such as Group, Holdings, International or UK, and JOA cannot confirm that it is this employer (entries with the same name are in hits with ambiguous true, the others in possible_names; hits can be empty). not_found means no entry of the registers read has this name and none contains it (JOA reads a register for that country, or every register with no country). no_register means JOA reads no register for that country, so it cannot say either way. invalid (POST only) means this employer could not be looked up as sent (reason is the error code, hint says what is wrong); error means JOA could not look up this one employer this time (reason lookup_failed). Neither is charged and the other employers of the call are answered.",
            "enum": [
              "matched",
              "ambiguous",
              "not_found",
              "excluded",
              "no_register",
              "invalid",
              "error"
            ],
            "type": "string"
          },
          "suggested_name": {
            "description": "On ambiguous only. The printed legal name of the ONE register entry that is, or contains, the name sent, when the name was sent without a legal form (\"Monzo\" gives \"Monzo Bank Ltd\"). A lead, never a match. Check that it is your employer, then send it as the name in a second call, which matches. Never set for a twin of a name sent with a legal form (Holdings, Group, International, UK, a country word, plc against Ltd) and never when more than one candidate exists.",
            "type": "string"
          }
        },
        "required": [
          "input",
          "status",
          "matched",
          "hits"
        ],
        "type": "object"
      },
      "VisaCheckSource": {
        "description": "One official document behind a visa check (added 11 Nov 2026).",
        "properties": {
          "doc": {
            "description": "The document as its publisher names it.",
            "type": "string"
          },
          "para": {
            "description": "The part of the document (paragraph, table, row, section).",
            "type": "string"
          },
          "url": {
            "description": "The official page or file.",
            "format": "uri",
            "type": "string"
          },
          "version": {
            "description": "The version or date of the document as JOA read it.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "WithdrawnJob": {
        "description": "What GET /v1/jobs/{id} answers for a withdrawn listing. No job details.",
        "properties": {
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "status": {
            "enum": [
              "withdrawn"
            ],
            "type": "string"
          },
          "withdrawn_at": {
            "format": "date-time",
            "type": "string"
          },
          "withdrawn_reason": {
            "$ref": "#/components/schemas/WithdrawnReason"
          }
        },
        "required": [
          "id",
          "status",
          "withdrawn_at",
          "withdrawn_reason"
        ],
        "type": "object"
      },
      "WithdrawnReason": {
        "description": "Why a role left the served set, as a public category (computed when you ask): `employer` (the employer\nwithdrew it or opted out), `duplicate` (a duplicate of another listing), `unverified` (JOA could not\nconfirm it recently; usually comes back), `apply_link` (its apply link stopped working), `quality` (it no\nlonger meets a serving rule), `policy` (the source may no longer be shown, or the row was removed),\n`closed` (it has closed since; also in /v1/jobs/expired), `other` (in transition), `country_corrected`\n(we corrected the job's country, so it no longer belongs to the country you filter by; it may still be\nserved under its new country; listed only when you pass `country` or your key has a country lock, once,\nat the correction).\n",
        "enum": [
          "employer",
          "duplicate",
          "unverified",
          "apply_link",
          "quality",
          "policy",
          "closed",
          "other",
          "country_corrected"
        ],
        "type": "string"
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "description": "`Authorization: Bearer YOUR_API_SECRET`",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "Every listing here comes from an employer ATS, a company's own careers page,\na public employment agency, or a direct submission. Redistribution is\nenforced by a database JOIN, not a filter someone can forget.\n\nThree things this API does that a job feed normally does not:\n\n* **It says which fields it guessed.** Every job carries `field_sources`,\n  naming each field as `published` (carried by the source), `inferred`\n  (derived by us) or `absent`. 79.1% of live listings have an *inferred*\n  remote status; 20.8% have one the source actually stated. Filter with\n  `remote_confirmed=true` to get only the latter.\n* **It says when each row was last verified.** `last_verified_at` is the last\n  positive confirmation at the source (the posting's own page or ATS API record\n  found live, or the posting listed in a fresh read of the employer's job list;\n  otherwise its first harvest), not when it was posted; `last_verified_via` names\n  which. `GET /v1/meta/freshness` publishes the coverage numbers.\n* **It keeps what closed.** `GET /v1/jobs/closed` returns roles that have\n  come off their source, with the reason and the date. A req that opened\n  and closed in nine days is a hiring signal, not a dead link. The date is\n  the day JOA's daily verification confirmed the advert had gone; before\n  late September 2026 that verification ran in large catch-up batches, so\n  earlier closure dates show when JOA confirmed a closure, not when the\n  employer closed the role.\n\nChangelog 2026-10-07: new contract fields `engagement`,\n`contract_category`, `agency` and `working_schedule`, each with\n`field_sources` provenance and filters (`?engagement=`,\n`?contract_category=`, `?agency=`, `?working_schedule=`; absence token\n`unknown`, alias `not_stated`). Values appear only when the posting or the\nsource states them (or, later, when an audited rule establishes them):\nmost postings will show `unknown` at launch, and that is the honest answer,\nnot a defect. `contract_category=permanent` returns only postings that\nSTATE permanence. Per-field coverage is published on /public/coverage.\n`employment_type` is unchanged and frozen.\n\nCounts in this document are not typed in: they come from the daily\nstatistics snapshot every page of the website uses (GET /public/site-stats):\n2,443,847 live employer-direct listings (employer_direct_live) and\n153,072 employers as of 2026-11-17.\n\nThis service uses the ESCO classification of the European Commission.\nOccupation matches (`esco_occupation_uri`, `esco_occupation_label`,\n`isco_code`) are our automated inference from the job title, not the\nemployer's classification and not an official ESCO product; they are\nmarked `inferred` in `field_sources.occupation` and left out when the\ntitle is not an exact match.\n",
    "summary": "A verified ledger of open jobs, with per-field provenance and closure history.",
    "title": "Job Opportunities API",
    "version": "2026-11-11"
  },
  "openapi": "3.1.0",
  "paths": {
    "/public/companies/{slug}/open-roles-history": {
      "get": {
        "description": "Keyless. Reads a snapshot of joa.companies.open_roles (already maintained by\nrefresh_companies()), taken by joa.snapshot_company_open_history() into\njoa.company_open_history: never a job row, never a salary or time-to-fill figure.\nSnapshots are daily from 2026-10-06. Before that only two snapshots exist\n(2026-09-28 and 2026-10-04), so older windows have gaps; nothing is reconstructed\nat present. Each point carries a \"method\": \"snapshot\" (a count recorded that day) or\n\"reconstructed\" (a value derived afterwards from the ledger; a reconstructed point never\nreplaces a snapshot). An unknown slug returns 200 with an empty points array rather\nthan 404. Edge-cached \u003e=1h.\n",
        "operationId": "getCompanyOpenRolesHistory",
        "parameters": [
          {
            "in": "path",
            "name": "slug",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Window size. Defaults to 30.",
            "in": "query",
            "name": "days",
            "schema": {
              "enum": [
                30,
                90,
                365
              ],
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "beta": {
                          "type": "boolean"
                        },
                        "days_requested": {
                          "type": "integer"
                        },
                        "history_starts": {
                          "format": "date",
                          "nullable": true,
                          "type": "string"
                        },
                        "note": {
                          "type": "string"
                        },
                        "partial_data": {
                          "type": "boolean"
                        },
                        "points": {
                          "items": {
                            "properties": {
                              "date": {
                                "format": "date",
                                "type": "string"
                              },
                              "method": {
                                "description": "How the point was obtained.",
                                "enum": [
                                  "snapshot",
                                  "reconstructed"
                                ],
                                "type": "string"
                              },
                              "open_roles": {
                                "type": "integer"
                              }
                            },
                            "type": "object"
                          },
                          "type": "array"
                        },
                        "slug": {
                          "type": "string"
                        }
                      },
                      "type": "object"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "A daily open-roles trend for the named company."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        },
        "security": [],
        "summary": "BETA: partial data. One company's open-roles count over 30/90/365 days; real daily snapshots from 2026-10-06.",
        "tags": [
          "public"
        ]
      }
    },
    "/public/market-signals/history": {
      "get": {
        "description": "Keyless. Reads a once-a-day snapshot of the same rollup GET /public/market-signals\nreads live (joa.market_signal_segments), taken by joa.snapshot_market_signal_history()\n(db/193) into joa.market_signal_history. History begins the day the daily snapshot\nfirst ran (there is no backfill), and every response carries \"beta\": true,\n\"partial_data\": true and \"history_starts\" so a caller cannot mistake a short series\nfor a long one. Same restriction as the live endpoint: family/country/seniority only,\nno title, no company. Edge-cached \u003e=1h.\n",
        "operationId": "getMarketSignalsHistory",
        "parameters": [
          {
            "description": "One value of the family facet of /public/facets.",
            "in": "query",
            "name": "family",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "ISO 3166-1 alpha-2.",
            "in": "query",
            "name": "country",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "One value of the seniority facet of /public/facets.",
            "in": "query",
            "name": "seniority",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Window size. Defaults to 30.",
            "in": "query",
            "name": "days",
            "schema": {
              "enum": [
                30,
                90,
                365
              ],
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "beta": {
                          "type": "boolean"
                        },
                        "days_requested": {
                          "type": "integer"
                        },
                        "history_starts": {
                          "description": "Earliest date any snapshot exists, across every segment. Null before the first snapshot has ever run.",
                          "format": "date",
                          "nullable": true,
                          "type": "string"
                        },
                        "note": {
                          "type": "string"
                        },
                        "partial_data": {
                          "type": "boolean"
                        },
                        "points": {
                          "items": {
                            "properties": {
                              "closed": {
                                "type": "integer"
                              },
                              "companies": {
                                "type": "integer"
                              },
                              "date": {
                                "format": "date",
                                "type": "string"
                              },
                              "listings": {
                                "type": "integer"
                              },
                              "open": {
                                "type": "integer"
                              },
                              "state": {
                                "enum": [
                                  "published",
                                  "suppressed"
                                ],
                                "type": "string"
                              }
                            },
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "A daily trend for the requested segment, oldest first."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        },
        "security": [],
        "summary": "BETA: partial data. Daily trend of Market Signals segments (salary percentiles, time-to-fill, listing counts) over 30/90/365 days.",
        "tags": [
          "public"
        ]
      }
    },
    "/public/site-stats": {
      "get": {
        "description": "Keyless. The single source of every headline number on\njobopportunitiesapi.org, /public/stats, /public/coverage, llms.txt and\napis.json. Taken once a day (normally ~05:00 UTC, from a coverage report measured minutes earlier); `as_of` names the day.\nEvery surface shows the same values for the same `as_of`.\n\n`metrics.employer_direct_live` is THE live count: adverts a caller can\nobtain from /v1/jobs. `live_including_withheld` and\n`employers_including_withheld` include adverts JOA holds back and are\nnever the number JOA sells. `closed_with_closure_date` carries the\nclosure-date caveat in `closure_date_note`. Regional totals state their\ncountry sets in `regions`.\n",
        "operationId": "getSiteStats",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "as_of": {
                      "format": "date",
                      "type": "string"
                    },
                    "closure_date_note": {
                      "type": "string"
                    },
                    "definitions": {
                      "additionalProperties": {
                        "type": "string"
                      },
                      "type": "object"
                    },
                    "frozen_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "measured_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "metrics": {
                      "properties": {
                        "closed_with_closure_date": {
                          "type": "integer"
                        },
                        "countries_with_live_roles": {
                          "type": "integer"
                        },
                        "country_unknown_live": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "employer_direct_live": {
                          "type": "integer"
                        },
                        "employers": {
                          "type": "integer"
                        },
                        "employers_including_withheld": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "europe_live": {
                          "type": "integer"
                        },
                        "listings_ledger_rows": {
                          "type": "integer"
                        },
                        "live_including_withheld": {
                          "type": "integer"
                        },
                        "north_america_live": {
                          "type": "integer"
                        },
                        "posted_last_7d": {
                          "type": "integer"
                        },
                        "withheld_listings": {
                          "type": "integer"
                        }
                      },
                      "type": "object"
                    },
                    "regions": {
                      "type": "object"
                    },
                    "stale": {
                      "description": "true when measured_at is older than stale_after_hours (30): a daily snapshot was missed.",
                      "type": "boolean"
                    },
                    "stale_after_hours": {
                      "type": "integer"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "The daily snapshot."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "description": "No snapshot has been taken yet."
          }
        },
        "security": [],
        "summary": "The site's headline numbers, one name and one definition each (daily snapshot).",
        "tags": [
          "public"
        ]
      }
    },
    "/v1/changes": {
      "get": {
        "description": "Poll this instead of re-reading the ledger. Pass `since` on the first\ncall and the returned `next_since` from then on; it is a keyset cursor\nof `\u003ctimestamp\u003e|\u003cuuid\u003e`, so no row is lost to a shared timestamp.\n\n**What an event is (since 23 Oct 2026).** Events are relative to what we\nserve: a row entering the served set (`created`, or `updated` when it comes\nback), a served row whose content changed (`updated`), a served row leaving\nit (`withdrawn` or `delisted`). A row we never served is not an event and is\nnot billed. A change is usually published within a minute or two of\nbeing committed (removals first; a bulk correction of many rows can\ntake a few minutes longer), and `next_since` never moves past one that\nis still being written. An event carries the row as it is when the\nevent is published: a row that changed twice between two of your polls\narrives once, in its latest state. When a row may no longer be shown at all (an employer\nopt-out, a source we may not redistribute, a deleted row) its event carries\nonly `job.id` and `job.status`.\n\n**The restatement of 23 Oct 2026.** The feed restated itself once, free of\ncharge: every row we serve as `updated`, every open row we do not serve as\n`withdrawn`, every closure since 22 Sep 2026 as `delisted` (`withdrawn` where\nthe row may no longer be shown). The earlier feed could leave rows in a\nmirror that we no longer serve, and could skip a re-admission or a closure;\napplying the restatement brings any mirror built from it back to exactly\nwhat we serve.\n\n**New: `change: \"withdrawn\"`.** A row can leave the served set without\nbeing closed by the employer, because we judged it no longer meets the\nemployer-direct promise this API is sold on. Until now those rows simply\nstopped being mentioned, which meant a mirror built from this feed kept\nserving them indefinitely. `withdrawn` says so explicitly.\n\nTreat it exactly as you treat `delisted`: stop serving the row. The\ndifference is only in why. `delisted` means the vacancy is gone;\n`withdrawn` means the vacancy may well still exist, but we are no longer\nwilling to stand behind the link, most often because it points at a\ngovernment or aggregator portal rather than at the employer.\n\nA withdrawn row keeps its id. If we later judge it servable again it\nreturns as `updated`, so a mirror keyed on id needs no special handling.\n\nRoles an employer pushes to us directly follow the same\nrule: pausing, unlisting or deleting one is `withdrawn` (its job\ncarries no `closed_at`: it is not a closure), closing it or letting\nits deadline pass is `delisted` with `closed_reason`\n`employer_closed` or `deadline_passed`, and publishing it again\nis `updated` under the same id.\n\nIf your integration switches on `change`, add the new value before\nupgrading. An unknown-value branch that ignores it will keep serving\nrows we have withdrawn.\n\n**What `updated` means.** `updated` is emitted when a job's visible\ncontent changed (title, description, company, location, salary,\nemployment type, apply link, ...), when a closed job was re-opened,\nwhen a withdrawn job was restored, or when a copy of a job took over\nfrom a duplicate we stopped serving (that copy's id may be new to you:\nupsert on `id`; such a hand over and the matching `withdrawn` of the\nduplicate are corrections, free).\nA duplicate we stop serving arrives as `withdrawn` with\n`correction: true`. Only a change the employer made is billed; see below.\nRe-verifying that a job is still open does NOT produce an event: `last_seen_at` is a verification\ntimestamp, not a change timestamp, and `created` / `updated`\ntherefore no longer fire for every live job every day. A re-opened job\nkeeps its original id and `first_seen_at` and arrives as `updated`,\nnever as `created`: upsert on `id`.\n\n**Corrections are not billed (since 23 Oct 2026).** When we correct our\nown data in bulk (an employer name we fixed, a field we back-filled, a\nrow a quality rule removes), the events that correction causes carry\n`correction: true` and are not billed: you are never charged for\nreceiving our fix, and a large correction cannot use up your allowance.\nA row that is new to you (`created`) is billed as usual, whoever caused it.\n\n**`updated` is billed only when the employer changed the job.** An\n`updated` event of a job you already have is billed when the employer\nchanged what they state: title, description, apply link, employment\ntype, location text, or a remote type or salary they state. A change\nthat comes from our own processing (company name and slug, structured\nlocation, category and seniority, a salary we parsed or normalised,\nposting date fixes, a description we fetched for a job that came\nwithout one or with a short stub) is delivered as `updated` with\n`correction: true` and is not billed. You receive every change either\nway; apply them alike. A job that returns after it was withdrawn or\nclosed arrives as `updated` and is billed as before, except a return\nwithin 6 hours of our own re-check reopening it, which is free.\n\n**A job whose country changes leaves your country filter as `withdrawn`.**\nWhen the country of a job you received changes (most often our\ncorrection of a country we had wrong), a poll filtered by country, with\n`country=` or a key country lock, that matched the old country and does\nnot match the new one receives the job as `withdrawn` with\n`correction: true`, carrying only `job.id` and `job.status`. It is not\nbilled. It is sent once, at the move: a later event of that job (an\nedit, its closure) is not sent again to a poll that already has the\nmove, because you removed the job when you got it. If the job comes back\nto your country, it reaches your poll like any other change of it: for\nour correction, `updated` with `correction: true`, free. A poll that\nmatches the new country receives the change like any other change of\nthe job.\n\n**Billing follows the same rule.** Each event is one record, and since\nthe content clock went live (18 Oct 2026) a verification heartbeat is\nnot an event, so it is not billed. Content changes made before the\nclock went live were not recorded: if you need a baseline, page\n/v1/jobs once, then follow this feed.\n",
        "operationId": "listChanges",
        "parameters": [
          {
            "$ref": "#/components/parameters/IncludeEmbedding"
          },
          {
            "description": "Restrict the change feed to these upper-cased ISO country codes\n(comma-separated, up to 12, same semantics as /v1/jobs). A\nkey country lock applies alongside this filter.\n",
            "in": "query",
            "name": "country",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "since",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 500,
              "maximum": 5000,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "data": {
                      "items": {
                        "properties": {
                          "change": {
                            "description": "`created` entered the served set for the first time since your cursor ·\n`updated` its content moved ·\n`withdrawn` still open, but no longer served by us,\nso stop serving it ·\n`delisted` the vacancy itself is gone.\n",
                            "enum": [
                              "created",
                              "updated",
                              "withdrawn",
                              "delisted"
                            ],
                            "type": "string"
                          },
                          "correction": {
                            "description": "Present, and true, only on an event caused by our own processing:\na bulk correction of our data, or an `updated` event of a job you\nalready have whose change came from us and not from the employer\n(see What `updated` means), or a `withdrawn` sent because the job's\ncountry moved out of your country filter or key lock. Such an event\nis not billed. Apply it like any other event.\n",
                            "type": "boolean"
                          },
                          "job": {
                            "anyOf": [
                              {
                                "$ref": "#/components/schemas/Job"
                              },
                              {
                                "properties": {
                                  "id": {
                                    "format": "uuid",
                                    "type": "string"
                                  },
                                  "status": {
                                    "enum": [
                                      "withdrawn",
                                      "closed"
                                    ],
                                    "type": "string"
                                  }
                                },
                                "required": [
                                  "id",
                                  "status"
                                ],
                                "type": "object"
                              }
                            ],
                            "description": "The row as GET /v1/jobs/{id} shows it. When the row may no longer be\nshown at all (an employer opt-out, a source we may not redistribute, a\ndeleted row) only `id` and `status` are present.\n"
                          }
                        },
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "next_since": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "A page of changes."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/RecordQuotaExhausted"
          },
          "403": {
            "$ref": "#/components/responses/PlanUpgradeRequired"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Delta feed: created, updated, withdrawn and delisted, in change order.",
        "tags": [
          "jobs"
        ]
      }
    },
    "/v1/companies": {
      "get": {
        "description": "Every company here has at least one live listing you can fetch, so\n`open_roles` and `GET /v1/jobs?company=\u003cslug\u003e` reconcile. That is the\npoint of the endpoint: a directory entry advertising roles the API will\nnot serve is a broken promise.\n\nFurther companies (22,138 when measured on 8 Aug 2026) were seen hiring on their own careers page,\nunder a source we do not redistribute. They carry `own_site_roles` and\n`open_roles: 0`, their individual pages resolve normally, and they are\nincluded only with `include_discovered=true`: they are evidence a\ncompany is hiring, not inventory you can buy.\n\nOrdered by `GREATEST(open_roles, own_site_roles) DESC, name, slug`. The\nslug makes the ordering total: without it ties could be reordered\nbetween two requests (measured 3 Aug 2026: 18,213 tie groups covering\n36,464 of 186,558 companies, 19.5%), so offset paging silently repeated\nand skipped rows.\n\n`offset` is capped at 100,000 and an offset beyond that is a **422**, not\na silently clamped 200. Use `cursor` for deep paging: it is lossless and\nhas no limit.\n",
        "operationId": "listCompanies",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 25,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "maximum": 100000,
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "The next_cursor from the previous page. Overrides offset.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "country",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "org_type",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "source_type",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only companies whose domain we fetched and found their own name on.\nAn absent website means we could not prove one, not that they have none.\n",
            "in": "query",
            "name": "has_website",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "description": "Also return the companies we watched hiring on their own careers page\nunder a source we do not redistribute. They arrive with\n`open_roles: 0` and a non-zero `own_site_roles`, and `careers_url`\npoints at the page we saw them on. Useful for enrichment; not\ninventory.\n",
            "in": "query",
            "name": "include_discovered",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "q",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyPage"
                }
              }
            },
            "description": "A page of companies."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/RecordQuotaExhausted"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Employers whose live roles this API returns.",
        "tags": [
          "companies"
        ]
      }
    },
    "/v1/companies/{slug}": {
      "get": {
        "operationId": "getCompany",
        "parameters": [
          {
            "in": "path",
            "name": "slug",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Company"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "The company."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/RecordQuotaExhausted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "One employer.",
        "tags": [
          "companies"
        ]
      }
    },
    "/v1/export": {
      "get": {
        "description": "One JSON object per line, not a JSON array: the stream can be processed as it arrives, and a dropped connection costs one line rather than the whole document. Requires a plan with `bulk_export`.\nRows are ordered by `id`, so an interrupted transfer resumes exactly where it stopped. Pass the last id you received as `after`. On a multi-gigabyte export that is not a rare need.\nRecords are charged in batches as they are written, not at the end, so an export that is abandoned partway is still billed for what it delivered. If the monthly allowance runs out mid-stream, the last line of the body is an object carrying `error: record_quota_exhausted` and the `after` cursor to resume from. A consumer must therefore check the final line rather than assume a clean end of stream.\nEvery filter from `GET /v1/jobs` applies. Parameters that have no meaning on an id-ordered stream are refused with **400** `unsupported_parameter` before anything is charged: `limit` (the export has none, it streams every matching row), `cursor` and `offset` (resume with `after`), `sort`, `include_total`, `quality`, `include_poster_type`. An unknown parameter is a **400** `unknown_parameter`. Until 23 Oct 2026 such parameters were silently ignored, so `limit=1` streamed a whole country.\nPersonal contact details removed: when `include_description=true`, recruiter email addresses and phone numbers found inside the advert body are replaced with `[contact removed — see apply_url]` before the row is written. `apply_url` and every other field are unchanged. `GET /v1/jobs` and `GET /v1/jobs/{id}` apply a narrower rule instead: they remove only email addresses that identify a person (see the `description` field), keep company mailboxes such as `jobs@`, and leave phone numbers unchanged.\n",
        "operationId": "exportJobs",
        "parameters": [
          {
            "description": "Resume cursor: the `id` of the last row you received.",
            "in": "query",
            "name": "after",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "schema": {
              "default": "live",
              "enum": [
                "live",
                "closed",
                "any"
              ],
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IncludeDescription"
          },
          {
            "$ref": "#/components/parameters/Category"
          },
          {
            "$ref": "#/components/parameters/Family"
          },
          {
            "$ref": "#/components/parameters/Country"
          },
          {
            "$ref": "#/components/parameters/Remote"
          },
          {
            "$ref": "#/components/parameters/Seniority"
          },
          {
            "$ref": "#/components/parameters/Provider"
          },
          {
            "$ref": "#/components/parameters/SourceType"
          },
          {
            "$ref": "#/components/parameters/Company"
          },
          {
            "$ref": "#/components/parameters/PostedAfter"
          },
          {
            "$ref": "#/components/parameters/VerifiedAfter"
          },
          {
            "$ref": "#/components/parameters/PostedBefore"
          },
          {
            "$ref": "#/components/parameters/ListedBefore"
          },
          {
            "$ref": "#/components/parameters/VerifiedBefore"
          },
          {
            "$ref": "#/components/parameters/HasSalary"
          },
          {
            "$ref": "#/components/parameters/HasDescription"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/x-ndjson": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            },
            "description": "A stream of listings, one JSON object per line."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/RecordQuotaExhausted"
          },
          "403": {
            "$ref": "#/components/responses/PlanUpgradeRequired"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Bulk export of the full corpus, as a stream of NDJSON.",
        "tags": [
          "jobs"
        ]
      }
    },
    "/v1/export-packs": {
      "get": {
        "description": "Newest first, up to 50. Each row carries `status` (`queued`, `running`, `completed`, `failed`) and, once completed, a signed `download_url`.\n",
        "operationId": "listExportPacks",
        "responses": {
          "200": {
            "description": "This account's export packs."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "summary": "BETA: list this account's export packs.",
        "tags": [
          "jobs"
        ]
      },
      "post": {
        "description": "Requires a plan with `bulk_export` (same gate as `GET /v1/export`). Creates a background job that pages the full corpus for one country (optionally narrowed to one `category`/family), writes a gzip CSV file server-side, and meters the rows exactly like `GET /v1/jobs`. One in-flight pack per account. Poll `GET /v1/export-packs/{id}` for status; a completed pack carries a signed, expiring `download_url` valid for 7 days. BETA: row caps per plan are provisional and the file is deleted 7 days after completion.\n",
        "operationId": "createExportPack",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "country": {
                    "description": "Two-letter country code, e.g. DE.",
                    "type": "string"
                  },
                  "family": {
                    "description": "Optional job-family filter (the same vocabulary as `category`).",
                    "type": "string"
                  }
                },
                "required": [
                  "country"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "The pack was queued."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PlanUpgradeRequired"
          },
          "409": {
            "description": "An export pack is already queued or running for this account."
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        },
        "summary": "BETA: queue a background whole-country export pack.",
        "tags": [
          "jobs"
        ]
      }
    },
    "/v1/export-packs/{id}": {
      "get": {
        "operationId": "getExportPack",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The pack's current status."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "summary": "BETA: one export pack's status.",
        "tags": [
          "jobs"
        ]
      }
    },
    "/v1/help": {
      "get": {
        "description": "The API describing itself, machine readable. Also served keyless as\n`/public/help`, because an agent should be able to read the contract\nbefore it has a key. It is versioned (`help_version` for the shape of\nthe document, `grammar_version` for the query grammar) and additive\nwithin a version, so a cached copy stays usable; the `ETag` marks the\ndocument version and `If-None-Match` answers 304. The query grammar it\nstates is the grammar the parser implements (`a b OR c d` is\n`(a b) OR (c d)` since 25 Oct 2026), and a test keeps the two in step.\n",
        "operationId": "getHelp",
        "responses": {
          "200": {
            "description": "The help document, as application/json."
          },
          "304": {
            "description": "Not modified, the ETag you sent is already current."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        },
        "summary": "This document, with every endpoint and parameter, the query grammar, the limits, the error codes and a worked example per endpoint.",
        "tags": [
          "meta"
        ]
      }
    },
    "/v1/jobs": {
      "get": {
        "description": "Keyset pagination on `(posted_at DESC NULLS LAST, id DESC)`. Pass the\n`next_cursor` from each response back as `cursor`. Offsets are not\noffered here: at this scale they double-count when rows shift. A\nnon-zero `offset` is a **422** `offset_not_supported`, not silently\nignored (it used to return page one again).\n\nAn empty first page of a live search carries `hints`: why nothing\nmatched, as checked at that moment (12 Nov 2026; see JobPage.hints).\n`?city=` ignores accents for most cities: Medellin also finds Medellín.\n\n**Records charged:** one per row returned, except a job that was already charged to your key on this endpoint in the previous 24 hours, which costs 0. `X-JOA-Records-Repeated` says how many rows of the response were free for that reason. The same page asked for again within 15 minutes with the same answer also costs 0. `/v1/changes` is not affected: each event is one record.\n\n**Bad input is refused, never silently widened, and a refused request\ncosts no records** (checked before metering, 18 Oct 2026):\n`limit` outside 1-200 or not a whole number -\u003e **422** `bad_limit`;\n`q`, `title`, `title_exclude`, `description_contains` or `company_name_contains` of 500 bytes or\nmore (200 until 2026-11-10) -\u003e **422** `filter_too_long` (these used to be dropped, returning the\nunfiltered ledger); a text filter with no word or number (operators\nonly) -\u003e **422** `query_has_no_terms`; a text filter the query grammar\ncannot honour (unmatched parenthesis, empty group, an operator without an\noperand) -\u003e **422** `query_syntax`; a boolean expression over the grammar limits (more than 32 terms or a prefix\nshorter than 3 characters; plain values have no such limit), or parentheses nested more than 8 deep in any value -\u003e **422**\n`query_too_complex`; a boolean flag that is not\n`true` or `false` (any case; since 18 Oct 2026 `1`/`0`/`yes`/`no` are refused too,\nthey used to be accepted silently) -\u003e **422** `bad_boolean`; `has_salary` other than\ntrue/structured/any/false -\u003e **422** `bad_has_salary`; `min_salary` /\n`max_salary` outside 0-10,000,000 (annual EUR) or not finite -\u003e **422**;\n`sort` while ranked search is not enabled on this deployment -\u003e **422**\n`sort_unavailable`; a NUL byte or invalid UTF-8 in any value -\u003e **422**\n`bad_parameter_value` (since 2026-11-11 also any value the database cannot convert, which answered\n500 `query_failed` before); an impossible cursor -\u003e **422** `bad_cursor`; `include_closed`, which only\n`GET /v1/jobs/{id}` reads, -\u003e **400** `unsupported_parameter` naming `GET /v1/jobs/closed` and\n`status=any` (since 2026-11-11; it was accepted and ignored before).\nA plan whose page cap is below the requested `limit` (within 1-200)\nis served at the cap and says so in `X-JOA-Limit-Applied` and `Warning`.\n",
        "operationId": "listJobs",
        "parameters": [
          {
            "description": "1-200 (default 25). Anything else is a 422 `bad_limit`, not clamped.",
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 25,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The next_cursor from the previous page.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Employer flood control, opt-in (24 Oct 2026). `company` returns at\nmost ONE row per employer per request: the newest row the walk reaches\nfor that company in the published order, with the roles behind it read\nand hidden. Every returned row then carries\n`company_more_roles`. Without this parameter the response is exactly\nwhat it has always been.\n\nThe rows behind a collapsed row are NOT deferred: `next_cursor`\nresumes after the last row the request decided on, so a hidden row\nnever returns on a later page. A collapsed page therefore carries at\nmost `limit` rows and often fewer (one employer flooding the window\ncollapses to one row). Ordering is never changed: the published\n`posted_at DESC NULLS LAST, id DESC` contract holds. Counts are\nuntouched: `include_total` and every count surface still count\nmatching ROWS, not employers. Only the rows actually returned are\ncharged as records.\n",
            "in": "query",
            "name": "collapse",
            "schema": {
              "enum": [
                "company"
              ],
              "type": "string"
            }
          },
          {
            "description": "Employer flood control, opt-in (24 Oct 2026): at most N rows of one\nemployer per request (1-200). Rows beyond N are read and hidden where\nthey stand, never deferred to a later page, so a page carries at most\n`limit` rows and often fewer. Counts (`include_total`, the facet\nchips) still count every matching row. `max_per_company=1` agrees\nwith `collapse=company` and may be sent with it; any other value\ntogether with `collapse=company` is a **422**\n`flood_params_conflict`, because the two contradict each other.\nUnlike `collapse=company` it adds no field to the rows.\n",
            "in": "query",
            "name": "max_per_company",
            "schema": {
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "`live` (default) returns open vacancies. `closed` returns roles that\nhave left their source. `any` returns both; every row carries\n`status`. Paid endpoints only.\n",
            "in": "query",
            "name": "status",
            "schema": {
              "default": "live",
              "enum": [
                "live",
                "closed",
                "any"
              ],
              "type": "string"
            }
          },
          {
            "description": "Re-admits vacancies whose poster is a staffing agency or a job board.\nExcluded by DEFAULT: the posting is real and the apply link is the\nposter's own, but the poster is not the employer, and one agency with\nthousands of listings (18,000 in one case, measured 19 Aug 2026) can\nflood a category until search stops being useful.\nComma-separated. Paid endpoints only. An unrecognised value is a 422.\n",
            "in": "query",
            "name": "include_poster_type",
            "schema": {
              "enum": [
                "staffing",
                "jobboard",
                "all"
              ],
              "type": "string"
            }
          },
          {
            "description": "`all` re-admits rows we have GATED -- reversible doubt, such as a\nfuture `posted_at` or a missing apply URL. It never re-admits rows we\nhave REMOVED: those breach the employer-direct guarantee and no query\nparameter may opt back into it. Each returned row carries its verdict,\nits rule id and the matched host. Paid endpoints only.\n",
            "in": "query",
            "name": "quality",
            "schema": {
              "enum": [
                "all"
              ],
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/Category"
          },
          {
            "$ref": "#/components/parameters/Family"
          },
          {
            "$ref": "#/components/parameters/Country"
          },
          {
            "$ref": "#/components/parameters/City"
          },
          {
            "$ref": "#/components/parameters/State"
          },
          {
            "$ref": "#/components/parameters/Region"
          },
          {
            "$ref": "#/components/parameters/Remote"
          },
          {
            "$ref": "#/components/parameters/EmploymentType"
          },
          {
            "$ref": "#/components/parameters/Engagement"
          },
          {
            "$ref": "#/components/parameters/ContractCategory"
          },
          {
            "$ref": "#/components/parameters/AgencyFlag"
          },
          {
            "$ref": "#/components/parameters/WorkingSchedule"
          },
          {
            "$ref": "#/components/parameters/Seniority"
          },
          {
            "$ref": "#/components/parameters/Provider"
          },
          {
            "$ref": "#/components/parameters/ExcludeProvider"
          },
          {
            "$ref": "#/components/parameters/SourceType"
          },
          {
            "$ref": "#/components/parameters/ExcludeSourceType"
          },
          {
            "$ref": "#/components/parameters/Company"
          },
          {
            "$ref": "#/components/parameters/ExcludeCategory"
          },
          {
            "$ref": "#/components/parameters/ExcludeCountry"
          },
          {
            "$ref": "#/components/parameters/Language"
          },
          {
            "$ref": "#/components/parameters/LanguageExclude"
          },
          {
            "$ref": "#/components/parameters/CountryConfidence"
          },
          {
            "$ref": "#/components/parameters/CountryMatch"
          },
          {
            "$ref": "#/components/parameters/SponsorRegister"
          },
          {
            "$ref": "#/components/parameters/VisaText"
          },
          {
            "$ref": "#/components/parameters/CompensationType"
          },
          {
            "$ref": "#/components/parameters/ExcludeCompensationType"
          },
          {
            "$ref": "#/components/parameters/RemoteConfirmed"
          },
          {
            "$ref": "#/components/parameters/HasSalary"
          },
          {
            "$ref": "#/components/parameters/HasDescription"
          },
          {
            "$ref": "#/components/parameters/RequireFields"
          },
          {
            "$ref": "#/components/parameters/IncludeDescription"
          },
          {
            "$ref": "#/components/parameters/IncludeEmbedding"
          },
          {
            "$ref": "#/components/parameters/PostedAfter"
          },
          {
            "$ref": "#/components/parameters/VerifiedAfter"
          },
          {
            "$ref": "#/components/parameters/ListedAfter"
          },
          {
            "$ref": "#/components/parameters/PostedBefore"
          },
          {
            "$ref": "#/components/parameters/ListedBefore"
          },
          {
            "$ref": "#/components/parameters/VerifiedBefore"
          },
          {
            "$ref": "#/components/parameters/Since"
          },
          {
            "$ref": "#/components/parameters/Q"
          },
          {
            "$ref": "#/components/parameters/Title"
          },
          {
            "$ref": "#/components/parameters/TitleExclude"
          },
          {
            "$ref": "#/components/parameters/CompanyNameContains"
          },
          {
            "$ref": "#/components/parameters/DescriptionContains"
          },
          {
            "$ref": "#/components/parameters/CompanyDomain"
          },
          {
            "$ref": "#/components/parameters/ExcludeCompanyDomain"
          },
          {
            "$ref": "#/components/parameters/MinSalary"
          },
          {
            "$ref": "#/components/parameters/MaxSalary"
          },
          {
            "$ref": "#/components/parameters/SortRelevance"
          },
          {
            "$ref": "#/components/parameters/IncludeTotal"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobPage"
                }
              }
            },
            "description": "A page of listings."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/RecordQuotaExhausted"
          },
          "403": {
            "$ref": "#/components/responses/PlanUpgradeRequired"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Retry after `Retry-After` seconds; nothing is charged. `timeout`: the query ran past its\ntime limit (narrow the filter). `busy` (since 2026-11-11): too many requests carrying a\nboolean text expression are running at once; at most a few run together, each with a\n6 s budget, so one burst of heavy boolean searches cannot slow the API for everyone.\nPlain searches are never refused this way.\n"
          }
        },
        "summary": "List listings, newest first.",
        "tags": [
          "jobs"
        ]
      }
    },
    "/v1/jobs/closed": {
      "get": {
        "description": "Keyset pagination on `(closed_at DESC, id DESC)`.\n\nClosure dates: JOA records as the closure date the day its daily\nverification confirmed that an advert had gone. Before late September\n2026 that verification ran in large catch-up batches, so closure dates\nrecorded before then show when JOA confirmed a closure, not when the\nemployer closed the role; daily verification applies from late\nSeptember 2026.\n\n`closed_reason` is not decoration. `expired_upstream` means the radar\nproved the vacancy dead: two misses at least an hour apart, re-checked\nagainst the board listing or the job URL itself. `not_seen` means it\nsimply stopped appearing at its source for the grace period, which is\nusually a closure and occasionally a board that broke.\n`apply_link_dead` means the posting's own apply link kept failing at its\nsource: hidden after two independent failing checks, still failing on three\nor more consecutive checks at least 14 days later (HTTP 404/410, a page that\nsays the position is closed, the ATS API reporting it closed, or a host that\nno longer resolves).\n`employer_closed` and `deadline_passed` are stated by the employer\nitself, for roles the employer pushed to us directly: it closed the role,\nor its application deadline passed. A role an employer paused, unlisted\nor deleted is not a closure and is never here; /v1/changes reports it\nas `withdrawn`.\nFive rarer values close a row on JOA's own judgement of its apply\nlink, not because the employer closed the role: `aggregator_host`\n(the apply link led to a job aggregator, closed on 16 Aug 2026),\n`generic_apply_url` (a host-only link, or one link shared by five or\nmore different titles), `portal_apply_url` (a public employment\nportal page instead of the employer's own), `superseded_by_jobtech_loader`\n(a Swedish JobTech row replaced by the current loader on 2 Nov 2026)\nand `ai_verified_closed` (a review of the posting in a real browser\nfound it closed). Parse the field as an open set: treat any value you do not\nrecognise as closed. The `closed_reason` filter below accepts the\nfive main values only.\n\nEvery filter from `GET /v1/jobs` also applies here.\n",
        "operationId": "listClosedJobs",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 25,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "closed_after",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "closed_before",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "closed_reason",
            "schema": {
              "enum": [
                "expired_upstream",
                "not_seen",
                "apply_link_dead",
                "employer_closed",
                "deadline_passed",
                "aggregator_host",
                "generic_apply_url",
                "portal_apply_url",
                "superseded_by_jobtech_loader",
                "ai_verified_closed"
              ],
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/Category"
          },
          {
            "$ref": "#/components/parameters/Family"
          },
          {
            "$ref": "#/components/parameters/Country"
          },
          {
            "$ref": "#/components/parameters/City"
          },
          {
            "$ref": "#/components/parameters/State"
          },
          {
            "$ref": "#/components/parameters/Region"
          },
          {
            "$ref": "#/components/parameters/Remote"
          },
          {
            "$ref": "#/components/parameters/EmploymentType"
          },
          {
            "$ref": "#/components/parameters/Engagement"
          },
          {
            "$ref": "#/components/parameters/ContractCategory"
          },
          {
            "$ref": "#/components/parameters/AgencyFlag"
          },
          {
            "$ref": "#/components/parameters/WorkingSchedule"
          },
          {
            "$ref": "#/components/parameters/Seniority"
          },
          {
            "$ref": "#/components/parameters/Provider"
          },
          {
            "$ref": "#/components/parameters/ExcludeProvider"
          },
          {
            "$ref": "#/components/parameters/SourceType"
          },
          {
            "$ref": "#/components/parameters/ExcludeSourceType"
          },
          {
            "$ref": "#/components/parameters/Company"
          },
          {
            "$ref": "#/components/parameters/ExcludeCategory"
          },
          {
            "$ref": "#/components/parameters/ExcludeCountry"
          },
          {
            "$ref": "#/components/parameters/Language"
          },
          {
            "$ref": "#/components/parameters/LanguageExclude"
          },
          {
            "$ref": "#/components/parameters/CountryConfidence"
          },
          {
            "$ref": "#/components/parameters/CountryMatch"
          },
          {
            "$ref": "#/components/parameters/SponsorRegister"
          },
          {
            "$ref": "#/components/parameters/VisaText"
          },
          {
            "$ref": "#/components/parameters/CompensationType"
          },
          {
            "$ref": "#/components/parameters/ExcludeCompensationType"
          },
          {
            "$ref": "#/components/parameters/RemoteConfirmed"
          },
          {
            "$ref": "#/components/parameters/HasSalary"
          },
          {
            "$ref": "#/components/parameters/HasDescription"
          },
          {
            "$ref": "#/components/parameters/RequireFields"
          },
          {
            "$ref": "#/components/parameters/IncludeDescription"
          },
          {
            "$ref": "#/components/parameters/PostedAfter"
          },
          {
            "$ref": "#/components/parameters/VerifiedAfter"
          },
          {
            "$ref": "#/components/parameters/ListedAfter"
          },
          {
            "$ref": "#/components/parameters/PostedBefore"
          },
          {
            "$ref": "#/components/parameters/ListedBefore"
          },
          {
            "$ref": "#/components/parameters/VerifiedBefore"
          },
          {
            "$ref": "#/components/parameters/Since"
          },
          {
            "$ref": "#/components/parameters/Q"
          },
          {
            "$ref": "#/components/parameters/Title"
          },
          {
            "$ref": "#/components/parameters/TitleExclude"
          },
          {
            "$ref": "#/components/parameters/CompanyNameContains"
          },
          {
            "$ref": "#/components/parameters/DescriptionContains"
          },
          {
            "$ref": "#/components/parameters/CompanyDomain"
          },
          {
            "$ref": "#/components/parameters/ExcludeCompanyDomain"
          },
          {
            "$ref": "#/components/parameters/MinSalary"
          },
          {
            "$ref": "#/components/parameters/MaxSalary"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobPage"
                }
              }
            },
            "description": "A page of closed listings."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/RecordQuotaExhausted"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Roles that have left their source, most recently closed first.",
        "tags": [
          "jobs"
        ]
      }
    },
    "/v1/jobs/expired": {
      "get": {
        "description": "The cheap half of /v1/jobs/closed. Returns id, closed_at and closed_reason only: enough to mark rows stale in your own database without transferring the jobs themselves. About 89% smaller than the same page from /v1/jobs/closed.\n\nClosure dates: JOA records as the closure date the day its daily verification confirmed that an advert had gone. Before late September 2026 that verification ran in large catch-up batches, so closure dates recorded before then show when JOA confirmed a closure, not when the employer closed the role; daily verification applies from late September 2026.\nKeyset paged exactly like /v1/changes: pass `since` on the first call and the returned `next_since` from then on. An empty page echoes your cursor back, so the loop keeps working once you are current.\n\nOn every plan, including the free Explore plan (since 9 Nov 2026), with the plan's normal request limits: removing closed listings from your copy is an obligation on every customer. Not metered: it returns ids, not job rows, charges no records and sends no `X-RateLimit-Records-*` headers.\n",
        "operationId": "listExpiredJobs",
        "parameters": [
          {
            "description": "RFC3339 timestamp, or a `next_since` cursor from a previous call.",
            "in": "query",
            "name": "since",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "1-10000, default 1000.",
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 1000,
              "maximum": 10000,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "data": {
                      "items": {
                        "properties": {
                          "closed_at": {
                            "description": "JOA records as the closure date the day its daily verification confirmed that an advert had gone. Before late September 2026 that verification ran in large catch-up batches, so closure dates recorded before then show when JOA confirmed a closure, not when the employer closed the role; daily verification applies from late September 2026.",
                            "format": "date-time",
                            "type": "string"
                          },
                          "closed_reason": {
                            "enum": [
                              "expired_upstream",
                              "not_seen",
                              "apply_link_dead",
                              "employer_closed",
                              "deadline_passed",
                              "aggregator_host",
                              "generic_apply_url",
                              "portal_apply_url",
                              "superseded_by_jobtech_loader",
                              "ai_verified_closed"
                            ],
                            "type": "string"
                          },
                          "id": {
                            "format": "uuid",
                            "type": "string"
                          }
                        },
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "next_since": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "A page of closures."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PlanUpgradeRequired"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Ids of roles that have come off the ledger"
      }
    },
    "/v1/jobs/similar": {
      "get": {
        "description": "The nearest SERVED jobs to a query vector, by cosine similarity, with every `GET /v1/jobs` filter.\nThe query is the stored vector of a job (`job_id`, more like this; the job itself is never returned) or,\nwith POST, a vector you embedded yourself.\n\n**Vectors.** Documents are Qwen3-Embedding-8B embeddings of title, company, location and the start of the\nadvert (one per line, no instruction), first 1024 of 4096 dimensions, L2-normalised. Embed a QUERY with the\nsame model and exactly this text, where the line break is a real newline:\n`Instruct: Given a web search query, retrieve relevant job postings that match the query` then a newline, then\n`Query: \u003cyour query\u003e`. Keep the first 1024 dimensions and L2-normalise (the API normalises again).\n\n**Filters.** Every `/v1/jobs` filter applies, in the query string (also on POST). Not available: `cursor`,\n`offset`, `sort`, `include_total`, `status` other than live, `include_closed`, `collapse`,\n`max_per_company` (422 `parameter_not_supported`). There is no next page: the answer is the top `limit`.\n\n**Completeness.** `search.strategy` is `nearest_then_filter` (the nearest points, then the filters) or\n`exact_within_filter` (for a selective filter every matching job is scored exactly). `search.complete` false\nmeans the filter matched many jobs but few of the nearest ones, so fewer than `limit` came back; narrow the\nfilter or use `min_score`. A job without a vector yet (the newest postings) cannot be found.\n\n**Records charged:** one per row returned, like `/v1/jobs`. Every plan. Refusals cost nothing.\n",
        "operationId": "findSimilarJobs",
        "parameters": [
          {
            "description": "The uuid or slug of the job whose vector is the query.",
            "in": "query",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "1-200, default 20 (at most 100 with include=embedding, 50 with include_description=true). The plan's page cap applies.",
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 20,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Drop results whose cosine similarity is below this value (-1 to 1).",
            "in": "query",
            "name": "min_score",
            "schema": {
              "maximum": 1,
              "minimum": -1,
              "type": "number"
            }
          },
          {
            "$ref": "#/components/parameters/Category"
          },
          {
            "$ref": "#/components/parameters/Family"
          },
          {
            "$ref": "#/components/parameters/Country"
          },
          {
            "$ref": "#/components/parameters/City"
          },
          {
            "$ref": "#/components/parameters/State"
          },
          {
            "$ref": "#/components/parameters/Region"
          },
          {
            "$ref": "#/components/parameters/Remote"
          },
          {
            "$ref": "#/components/parameters/EmploymentType"
          },
          {
            "$ref": "#/components/parameters/Engagement"
          },
          {
            "$ref": "#/components/parameters/ContractCategory"
          },
          {
            "$ref": "#/components/parameters/AgencyFlag"
          },
          {
            "$ref": "#/components/parameters/WorkingSchedule"
          },
          {
            "$ref": "#/components/parameters/Seniority"
          },
          {
            "$ref": "#/components/parameters/Provider"
          },
          {
            "$ref": "#/components/parameters/ExcludeProvider"
          },
          {
            "$ref": "#/components/parameters/SourceType"
          },
          {
            "$ref": "#/components/parameters/ExcludeSourceType"
          },
          {
            "$ref": "#/components/parameters/Company"
          },
          {
            "$ref": "#/components/parameters/ExcludeCategory"
          },
          {
            "$ref": "#/components/parameters/ExcludeCountry"
          },
          {
            "$ref": "#/components/parameters/Language"
          },
          {
            "$ref": "#/components/parameters/LanguageExclude"
          },
          {
            "$ref": "#/components/parameters/CountryConfidence"
          },
          {
            "$ref": "#/components/parameters/CountryMatch"
          },
          {
            "$ref": "#/components/parameters/SponsorRegister"
          },
          {
            "$ref": "#/components/parameters/VisaText"
          },
          {
            "$ref": "#/components/parameters/CompensationType"
          },
          {
            "$ref": "#/components/parameters/ExcludeCompensationType"
          },
          {
            "$ref": "#/components/parameters/RemoteConfirmed"
          },
          {
            "$ref": "#/components/parameters/HasSalary"
          },
          {
            "$ref": "#/components/parameters/HasDescription"
          },
          {
            "$ref": "#/components/parameters/RequireFields"
          },
          {
            "$ref": "#/components/parameters/IncludeDescription"
          },
          {
            "$ref": "#/components/parameters/PostedAfter"
          },
          {
            "$ref": "#/components/parameters/VerifiedAfter"
          },
          {
            "$ref": "#/components/parameters/ListedAfter"
          },
          {
            "$ref": "#/components/parameters/PostedBefore"
          },
          {
            "$ref": "#/components/parameters/ListedBefore"
          },
          {
            "$ref": "#/components/parameters/VerifiedBefore"
          },
          {
            "$ref": "#/components/parameters/Q"
          },
          {
            "$ref": "#/components/parameters/Title"
          },
          {
            "$ref": "#/components/parameters/TitleExclude"
          },
          {
            "$ref": "#/components/parameters/CompanyNameContains"
          },
          {
            "$ref": "#/components/parameters/DescriptionContains"
          },
          {
            "$ref": "#/components/parameters/CompanyDomain"
          },
          {
            "$ref": "#/components/parameters/ExcludeCompanyDomain"
          },
          {
            "$ref": "#/components/parameters/MinSalary"
          },
          {
            "$ref": "#/components/parameters/MaxSalary"
          },
          {
            "$ref": "#/components/parameters/IncludeEmbedding"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimilarPage"
                }
              }
            },
            "description": "The nearest served jobs, most similar first."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/RecordQuotaExhausted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "501": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "`text_query_unavailable`: this server runs without a query embedder, so text queries are switched off (the normal service answers them). Embed the text yourself (see the description) and send it as `vector`. Nothing is charged.\n"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "`semantic_search_unavailable`: the vector service is briefly unreachable (or this is the read only standby, which has none). `text_search_busy` or `text_search_unavailable` (text queries only): the query embedder is saturated or briefly away; vector and job_id queries keep working. Retry after the `Retry-After` seconds. Nothing is charged.\n"
          }
        },
        "summary": "Semantic search, more like this job",
        "tags": [
          "jobs"
        ]
      },
      "post": {
        "description": "The nearest SERVED jobs to a query vector, by cosine similarity, with every `GET /v1/jobs` filter.\nThe query is the stored vector of a job (`job_id`, more like this; the job itself is never returned) or,\nwith POST, a vector you embedded yourself or a `text` the API embeds for you.\n\n**Vectors.** Documents are Qwen3-Embedding-8B embeddings of title, company, location and the start of the\nadvert (one per line, no instruction), first 1024 of 4096 dimensions, L2-normalised. Embed a QUERY with the\nsame model and exactly this text, where the line break is a real newline:\n`Instruct: Given a web search query, retrieve relevant job postings that match the query` then a newline, then\n`Query: \u003cyour query\u003e`. Keep the first 1024 dimensions and L2-normalise (the API normalises again).\n\n**Filters.** Every `/v1/jobs` filter applies, in the query string (also on POST). Not available: `cursor`,\n`offset`, `sort`, `include_total`, `status` other than live, `include_closed`, `collapse`,\n`max_per_company` (422 `parameter_not_supported`). There is no next page: the answer is the top `limit`.\n\n**Completeness.** `search.strategy` is `nearest_then_filter` (the nearest points, then the filters) or\n`exact_within_filter` (for a selective filter every matching job is scored exactly). `search.complete` false\nmeans the filter matched many jobs but few of the nearest ones, so fewer than `limit` came back; narrow the\nfilter or use `min_score`. A job without a vector yet (the newest postings) cannot be found.\n\n**Records charged:** one per row returned, like `/v1/jobs`. Every plan. Refusals cost nothing.\n\nThe body is one JSON object with exactly one of `job_id`, `vector` (1024 numbers) or `text` (up to 500\ncharacters). Filters and `limit` stay in the query string.\n\n**Text queries.** `{\"text\": \"night shift nurse\"}` is embedded for you with the same model and instruction, so\nyou need no model of your own. The text is normalised first (Unicode NFC, lower case, trimmed, spaces\ncollapsed), so case and spacing never change the answer. Records charged are the same as for any other\nsearch: one per row returned. A text the service has seen before is answered from a cache; a new one takes\nabout a tenth of a second more. Privacy: query texts are stored without any link to who searched (no key,\naccount or address), for caching and coverage statistics. A busy or unreachable query embedder answers 503\n`text_search_busy` or `text_search_unavailable` with `Retry-After`, nothing charged.\n",
        "operationId": "searchSimilarJobs",
        "parameters": [
          {
            "description": "1-200, default 20 (at most 100 with include=embedding, 50 with include_description=true). The plan's page cap applies.",
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 20,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Drop results whose cosine similarity is below this value (-1 to 1).",
            "in": "query",
            "name": "min_score",
            "schema": {
              "maximum": 1,
              "minimum": -1,
              "type": "number"
            }
          },
          {
            "$ref": "#/components/parameters/Category"
          },
          {
            "$ref": "#/components/parameters/Family"
          },
          {
            "$ref": "#/components/parameters/Country"
          },
          {
            "$ref": "#/components/parameters/City"
          },
          {
            "$ref": "#/components/parameters/State"
          },
          {
            "$ref": "#/components/parameters/Region"
          },
          {
            "$ref": "#/components/parameters/Remote"
          },
          {
            "$ref": "#/components/parameters/EmploymentType"
          },
          {
            "$ref": "#/components/parameters/Engagement"
          },
          {
            "$ref": "#/components/parameters/ContractCategory"
          },
          {
            "$ref": "#/components/parameters/AgencyFlag"
          },
          {
            "$ref": "#/components/parameters/WorkingSchedule"
          },
          {
            "$ref": "#/components/parameters/Seniority"
          },
          {
            "$ref": "#/components/parameters/Provider"
          },
          {
            "$ref": "#/components/parameters/ExcludeProvider"
          },
          {
            "$ref": "#/components/parameters/SourceType"
          },
          {
            "$ref": "#/components/parameters/ExcludeSourceType"
          },
          {
            "$ref": "#/components/parameters/Company"
          },
          {
            "$ref": "#/components/parameters/ExcludeCategory"
          },
          {
            "$ref": "#/components/parameters/ExcludeCountry"
          },
          {
            "$ref": "#/components/parameters/Language"
          },
          {
            "$ref": "#/components/parameters/LanguageExclude"
          },
          {
            "$ref": "#/components/parameters/CountryConfidence"
          },
          {
            "$ref": "#/components/parameters/CountryMatch"
          },
          {
            "$ref": "#/components/parameters/SponsorRegister"
          },
          {
            "$ref": "#/components/parameters/VisaText"
          },
          {
            "$ref": "#/components/parameters/CompensationType"
          },
          {
            "$ref": "#/components/parameters/ExcludeCompensationType"
          },
          {
            "$ref": "#/components/parameters/RemoteConfirmed"
          },
          {
            "$ref": "#/components/parameters/HasSalary"
          },
          {
            "$ref": "#/components/parameters/HasDescription"
          },
          {
            "$ref": "#/components/parameters/RequireFields"
          },
          {
            "$ref": "#/components/parameters/IncludeDescription"
          },
          {
            "$ref": "#/components/parameters/PostedAfter"
          },
          {
            "$ref": "#/components/parameters/VerifiedAfter"
          },
          {
            "$ref": "#/components/parameters/ListedAfter"
          },
          {
            "$ref": "#/components/parameters/PostedBefore"
          },
          {
            "$ref": "#/components/parameters/ListedBefore"
          },
          {
            "$ref": "#/components/parameters/VerifiedBefore"
          },
          {
            "$ref": "#/components/parameters/Q"
          },
          {
            "$ref": "#/components/parameters/Title"
          },
          {
            "$ref": "#/components/parameters/TitleExclude"
          },
          {
            "$ref": "#/components/parameters/CompanyNameContains"
          },
          {
            "$ref": "#/components/parameters/DescriptionContains"
          },
          {
            "$ref": "#/components/parameters/CompanyDomain"
          },
          {
            "$ref": "#/components/parameters/ExcludeCompanyDomain"
          },
          {
            "$ref": "#/components/parameters/MinSalary"
          },
          {
            "$ref": "#/components/parameters/MaxSalary"
          },
          {
            "$ref": "#/components/parameters/IncludeEmbedding"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "job_id": {
                    "type": "string"
                  },
                  "text": {
                    "description": "A search phrase in any language, embedded by the API with Qwen3-Embedding-8B and the query instruction.",
                    "maxLength": 500,
                    "type": "string"
                  },
                  "vector": {
                    "items": {
                      "type": "number"
                    },
                    "maxItems": 1024,
                    "minItems": 1024,
                    "type": "array"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimilarPage"
                }
              }
            },
            "description": "The nearest served jobs, most similar first."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/RecordQuotaExhausted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "501": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "`text_query_unavailable`: this server runs without a query embedder, so text queries are switched off (the normal service answers them). Embed the text yourself (see the description) and send it as `vector`. Nothing is charged.\n"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "`semantic_search_unavailable`: the vector service is briefly unreachable (or this is the read only standby, which has none). `text_search_busy` or `text_search_unavailable` (text queries only): the query embedder is saturated or briefly away; vector and job_id queries keep working. Retry after the `Retry-After` seconds. Nothing is charged.\n"
          }
        },
        "summary": "Semantic search by text, vector or job_id",
        "tags": [
          "jobs"
        ]
      }
    },
    "/v1/jobs/status": {
      "post": {
        "description": "For a copy you keep yourself (9 Nov 2026): send the ids you hold, get each one's current status without\nre-reading the rows. Per id: `status` (`live`, `closed`, `withdrawn` or `unknown`), exactly what\n`GET /v1/jobs/{id}` answers for that id with your key (the same serving rules and the same country\nlock), plus `closed_at` and `closed_reason` on a closed id, `withdrawn_at` and `withdrawn_reason`\non a withdrawn id, and `content_version`, `content_changed_at` and `last_verified_at` on a live or\nclosed id. Refetch a live id whose `content_version` differs from yours; drop a closed, withdrawn or\nunknown one. `unknown` means the id answers 404 on `GET /v1/jobs/{id}`. Ids come back in the order\nyou sent them; a repeated id is checked and counted once.\n\n**Price:** 0.1 record per id checked, rounded up per call (1000 ids = 100 records, 7 ids = 1 record).\nEvery id counts, whatever its status. `X-JOA-Records-Charged` says what was charged. The 15 minute\nrepeat rule applies as on every endpoint: the same ids in the same order answered with the same bytes\nwithin 15 minutes cost nothing.\n\n**Plans:** the plans that include the delta feed (Growth and up); others get 403\n`plan_upgrade_required`, naming the plan. No query parameters (400 `unknown_parameter`).\n",
        "operationId": "getJobsStatus",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "ids": [
                  "0b6f7c2e-1d3a-4f5b-9c8d-7e6f5a4b3c2d"
                ]
              },
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "ids": {
                    "items": {
                      "format": "uuid",
                      "type": "string"
                    },
                    "maxItems": 1000,
                    "minItems": 1,
                    "type": "array"
                  }
                },
                "required": [
                  "ids"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/JobStatus"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "One entry per distinct id, in request order."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PlanUpgradeRequired"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Status of up to 1000 job ids in one call",
        "tags": [
          "jobs"
        ]
      }
    },
    "/v1/jobs/withdrawn": {
      "get": {
        "description": "The sibling of /v1/jobs/expired. A role can leave what this API serves without closing: a duplicate or\nfreshness hold, a quality rule, the employer withdrawing it or opting out, a licence removal. Those ids are\nhere, with `withdrawn_at` (when it left) and `withdrawn_reason` (a public category, never an internal\nrule). Together with /v1/jobs/expired it covers every exit: drop both from your copy.\n\nWith `country` (or a key country lock) it also lists, once, a job whose country changed away from the countries\nyou filter by (most often our correction of a wrong country): `withdrawn_reason` is `country_corrected` and\n`withdrawn_at` is the time of the change. The job may still be served under its new country. Drop it from your\ncopy of the old country. It is listed once, at the change, and not again when the job changes or closes later.\nWithout a country filter or lock this does not happen.\n\nA withdrawn role can come back. It then leaves this feed and `GET /v1/jobs?listed_after=` finds it again\n(listed_after counts the latest time a role entered the served set). Replaying from an old cursor returns the\nroles that are withdrawn now, in the order they left. The record starts on 23 Oct 2026.\n\nKeyset paged exactly like /v1/jobs/expired and /v1/changes: pass `since`, then the returned\n`next_since`; an empty page echoes your cursor. On every plan, including the free Explore plan (since\n9 Nov 2026), with the plan's normal request limits: removing withdrawn listings from your copy is an\nobligation on every customer. Not metered: ids only, no records charged.\n",
        "operationId": "listWithdrawnJobs",
        "parameters": [
          {
            "description": "RFC3339 timestamp, or a `next_since` cursor from a previous call.",
            "in": "query",
            "name": "since",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "1-10000, default 1000.",
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 1000,
              "maximum": 10000,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "ISO 3166-1 alpha-2 codes, comma separated (up to 12). A locked key sees its own countries only.",
            "in": "query",
            "name": "country",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "data": {
                      "items": {
                        "properties": {
                          "id": {
                            "format": "uuid",
                            "type": "string"
                          },
                          "withdrawn_at": {
                            "format": "date-time",
                            "type": "string"
                          },
                          "withdrawn_reason": {
                            "$ref": "#/components/schemas/WithdrawnReason"
                          }
                        },
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "next_since": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "A page of withdrawals."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PlanUpgradeRequired"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Ids of roles that left the served set without closing",
        "tags": [
          "jobs"
        ]
      }
    },
    "/v1/jobs/{id}": {
      "get": {
        "description": "A served listing comes back in full (one record). A listing that WAS served and has since been withdrawn\n(anything but a closure: a hold, a quality rule, an employer withdrawal or opt-out, a licence removal)\nanswers 200 with `data` = `{id, status: \"withdrawn\", withdrawn_at, withdrawn_reason}` and nothing else,\non every plan, charged 0 records. A closed listing is unchanged: 404, or the closed row with\n`include_closed=true`. A pushed role its employer withdrew keeps answering 410.\n",
        "operationId": "getJob",
        "parameters": [
          {
            "description": "The uuid or the public slug.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Return the row even if it has been delisted. It carries `status=\"closed\"`.",
            "in": "query",
            "name": "include_closed",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/IncludeEmbedding"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/Job"
                        },
                        {
                          "$ref": "#/components/schemas/WithdrawnJob"
                        }
                      ]
                    },
                    "description": {
                      "description": "Kept for compatibility: the same value as `data.description`, after the same personal\ncontact redaction. Absent on a withdrawn row.\n",
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "The listing. A served row carries its advert text inside `data` (`data.description`, since 2026-11-11,\nomitted when the row has none) and the same value beside it as `description` (null when the row has none).\nRead `data.description`; the sibling is kept for compatibility. A withdrawn row has neither.\n"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/RecordQuotaExhausted"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "410": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "The employer withdrew this listing (a role the employer pushed to us directly that was paused, unlisted, closed, expired or deleted). Final for this id: stop serving it.\n"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "One listing, with its description.",
        "tags": [
          "jobs"
        ]
      }
    },
    "/v1/me": {
      "get": {
        "description": "Costs no records. `usage_today` counts REQUESTS today (the per_day burst limit); the billed unit is records: `records_used_month` of `records_limit_month` (null = unmetered key), resetting at `records_reset_at` (00:00 UTC on the 1st). With a country lock (`records_country_lock`) job rows in that country are not counted; company rows still are.\n",
        "operationId": "getMe",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "created": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "endpoints": {
                      "description": "The endpoints this key may call, as the public /v1 paths (for example /v1/jobs or /v1/export). null or empty means every endpoint the plan allows, which is every key that predates the setting. A call to an endpoint outside this list answers 403 key_endpoint_not_configured. The /v1/me family is always on whatever the list says.",
                      "items": {
                        "type": "string"
                      },
                      "type": [
                        "array",
                        "null"
                      ]
                    },
                    "key_id": {
                      "format": "uuid",
                      "type": "string"
                    },
                    "key_prefix": {
                      "type": "string"
                    },
                    "limits": {
                      "properties": {
                        "max_page_size": {
                          "type": "integer"
                        },
                        "per_day": {
                          "type": "integer"
                        },
                        "per_minute": {
                          "type": "integer"
                        },
                        "ranked_per_day": {
                          "type": "integer"
                        }
                      },
                      "type": "object"
                    },
                    "plan": {
                      "type": "string"
                    },
                    "records_continent_lock": {
                      "description": "Continent of a continent-locked Scale key (africa, asia, europe, north_america, oceania, south_america); job rows in its countries are not metered. Country list at /docs/account/record-meter#continent-locked.",
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "records_country_lock": {
                      "description": "ISO country of a country-locked key (job rows there are not metered).",
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "records_limit_month": {
                      "description": "Monthly record allowance; null for an unmetered key.",
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "records_reset_at": {
                      "description": "When the record allowance resets (1st of next month 00:00 UTC).",
                      "format": "date-time",
                      "type": "string"
                    },
                    "records_used_month": {
                      "description": "Records charged this calendar month (UTC).",
                      "type": "integer"
                    },
                    "renews_or_expires": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "status": {
                      "type": "string"
                    },
                    "usage_today": {
                      "description": "Requests today (not records).",
                      "type": "integer"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Key status."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Your key, plan and quota.",
        "tags": [
          "meta"
        ]
      }
    },
    "/v1/me/export-estimate": {
      "get": {
        "description": "Accepts the same filters as GET /v1/jobs. Free to call: it never returns rows and consumes no record quota. estimated_rows is the query planner's approximation (EXPLAIN, no execution), not an exact count.\n",
        "operationId": "getExportEstimate",
        "responses": {
          "200": {
            "description": "estimated_rows, export_cap, would_use, remaining_this_month, remaining_unlimited.\nremaining_this_month is the records left this month on the allowance the export\nspends from, or -1 when the key has no monthly allowance (kept for existing\nclients). remaining_unlimited (boolean, since 11 Nov 2026) is true exactly when\nremaining_this_month is -1; read it instead of testing for -1.\n"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Approximately how many rows a search would return, and whether the CSV export tool would use your plan's remaining allowance.",
        "tags": [
          "meta"
        ]
      }
    },
    "/v1/me/usage": {
      "get": {
        "operationId": "getMyUsage",
        "parameters": [
          {
            "description": "Only requests is available today.",
            "in": "query",
            "name": "metric",
            "schema": {
              "enum": [
                "requests"
              ],
              "type": "string"
            }
          },
          {
            "description": "Window size. Defaults to 30.",
            "in": "query",
            "name": "days",
            "schema": {
              "enum": [
                30,
                90
              ],
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Daily request counts, oldest first."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Requests served per day, for the dashboard's usage chart.",
        "tags": [
          "meta"
        ]
      }
    },
    "/v1/meta/facets": {
      "get": {
        "description": "Facet keys: `family`, `country`, `city`, `remote`, `employment`,\n`seniority`, `source_type`, `remote_source`, `provider`, `field`,\n`compensation_type` (db/370, the commission-only flag's live count:\nonly ever one value, `commission_only`), and the legacy `source`.\n\n`remote_source` counts the provenance split itself: how much of the\nledger's remote status is stated and how much is our inference.\n`provider` is every source name `?provider=` accepts, with its live row\ncount. `field` is how many live rows carry each field as `published`\nrather than inferred: the population `require_fields` selects from.\n",
        "operationId": "getFacets",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "additionalProperties": {
                        "items": {
                          "properties": {
                            "count": {
                              "type": "integer"
                            },
                            "label": {
                              "type": "string"
                            },
                            "value": {
                              "type": "string"
                            }
                          },
                          "type": "object"
                        },
                        "type": "array"
                      },
                      "type": "object"
                    },
                    "generated_at": {
                      "description": "When these counts were computed. The whole table is\nrebuilt in one transaction, so this describes all of it.\nWithout it, a facet total that differs from\n/public/coverage by a few thousand rows is\nindistinguishable from a real disagreement. The ledger\nmoves by thousands an hour.\n",
                      "format": "date-time",
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Facet counts."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Every filter value with its live count.",
        "tags": [
          "meta"
        ]
      }
    },
    "/v1/meta/freshness": {
      "get": {
        "description": "The claim the subscription is sold on, made checkable. Every live\nlisting is re-confirmed at its source on a rolling cycle; this reports\nthe coverage, plus per-field provenance totals so a buyer can size the\nhonest subset before they pay for it.\n",
        "operationId": "getFreshness",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "closures": {
                          "properties": {
                            "last_24h": {
                              "type": "integer"
                            },
                            "last_7d": {
                              "type": "integer"
                            }
                          },
                          "type": "object"
                        },
                        "field_coverage": {
                          "properties": {
                            "description": {
                              "type": "integer"
                            },
                            "employment_type": {
                              "type": "integer"
                            },
                            "remote_inferred": {
                              "type": "integer"
                            },
                            "remote_inferred_pct": {
                              "type": "number"
                            },
                            "remote_published": {
                              "type": "integer"
                            },
                            "remote_published_pct": {
                              "type": "number"
                            },
                            "salary_published": {
                              "type": "integer"
                            }
                          },
                          "type": "object"
                        },
                        "generated_at": {
                          "type": "string"
                        },
                        "live_listings": {
                          "type": "integer"
                        },
                        "verification": {
                          "properties": {
                            "newest_verification": {
                              "type": "string"
                            },
                            "oldest_verification": {
                              "type": "string"
                            },
                            "reverified_last_24h": {
                              "type": "integer"
                            },
                            "reverified_last_24h_pct": {
                              "type": "number"
                            },
                            "reverified_last_48h": {
                              "type": "integer"
                            },
                            "reverified_last_48h_pct": {
                              "type": "number"
                            },
                            "reverified_last_7d": {
                              "type": "integer"
                            },
                            "reverified_last_hour": {
                              "type": "integer"
                            }
                          },
                          "type": "object"
                        }
                      },
                      "type": "object"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Freshness and coverage report."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "How recently the ledger was verified, and how much of it is inferred.",
        "tags": [
          "meta"
        ]
      }
    },
    "/v1/meta/providers": {
      "get": {
        "description": "The list `?provider=` and `?exclude_provider=` accept. A value that is\nnot here is a 422, never a silently empty page, so you can always tell\n\"no jobs match\" from \"you spelled it wrong\".\n\nOnly redistributable sources appear. Sources JOA reads but does not\nrepublish are named at `GET /public/coverage` (`excluded_sources`).\n\nAlso served without a key at `GET /public/providers`, because \"which\nsources is this built from\" is a question you should be able to answer\nbefore creating an account.\n",
        "operationId": "listProviders",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "properties": {
                          "attribution": {
                            "description": "The words this source must be named with, where its licence requires it (Norway: \"NAV (arbeidsplassen.no)\"; UK: \"NHS Jobs\", Open Government Licence v3.0).\nAbsent for a source without such a rule.\n",
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "licence_name": {
                            "description": "The open licence the source publishes its vacancies under, named next to its credit (UK: \"Open Government Licence v3.0\"; France: \"Licence Ouverte 2.0 (Etalab)\" for Emploi-Territorial and Choisir le service public). Absent for a source without one.\n",
                            "type": "string"
                          },
                          "licence_url": {
                            "description": "The text of that licence. Present exactly when licence_name is. Licence Ouverte 2.0 asks for the source, a link to it and the date of last update: on each job, keep `attribution`, link the offer page (`source_url`, or `apply_url` when no separate source link is given) and show `last_verified_at` (the last time JOA read the offer at its source) next to `posted_at` (the publication date the source states).\n",
                            "type": "string"
                          },
                          "live_listings": {
                            "type": "integer"
                          },
                          "provider": {
                            "description": "The value to pass to ?provider=.",
                            "type": "string"
                          },
                          "source_class": {
                            "enum": [
                              "employer_ats",
                              "government",
                              "direct"
                            ],
                            "type": "string"
                          },
                          "source_type": {
                            "type": "string"
                          },
                          "with_description": {
                            "description": "How many of this source's live rows carry the\nemployer's advert text. Published including the\nsources where it is zero: three of them have no\nadapter in the description crawl at all, so they\ncontribute rows and no text, and\n`?provider=\u003cthat\u003e\u0026require_fields=description` returns\nan empty page. Knowing that here beats discovering it\nmid-evaluation.\n",
                            "type": "integer"
                          },
                          "with_description_pct": {
                            "type": "number"
                          }
                        },
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "generated_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "note": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "The provider list."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Every source the ledger is built from, with its live row count.",
        "tags": [
          "meta"
        ]
      }
    },
    "/v1/sponsors/lookup": {
      "get": {
        "description": "The one-employer form of `POST /v1/sponsors/lookup` (added 10 Nov 2026): the same answer for `name`,\noptional `country`, `town` and `region`. Works for any employer name, with or without JOA jobs.\n**Price:** 1 record per call (0.1 record per employer, rounded up per call), on every plan.\n**Legal note:** every answer carries `legal_note_code` (`immigration_information`) and `legal_note` at\nthe top level, as on the POST form.\n",
        "operationId": "lookupSponsor",
        "parameters": [
          {
            "description": "The employer name as you hold it (legal or trading name). At most 300 characters.",
            "in": "query",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "ISO 3166 two-letter country of the register to read (GB, US, NL, IE, CA, DK). Omit to read every register.",
            "in": "query",
            "name": "country",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The employer's town or city. Lets a name shared by several legal entities resolve to the one registered there.",
            "in": "query",
            "name": "town",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "US state (two letters or in full) for the US registers; with town, or alone for the name_region method. Only the US registers print a region, so it is ignored for every other country.",
            "in": "query",
            "name": "region",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/SponsorLookup"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/RecordQuotaExhausted"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Is this employer on an official sponsor register? One employer.",
        "tags": [
          "companies"
        ]
      },
      "post": {
        "description": "Added 10 Nov 2026. For each employer you name, whether it appears on an official government sponsor\nregister JOA reads: the UK Home Office register of licensed sponsors (GB), the IND public register of\nrecognised sponsors (NL), the SIRI fast-track certified companies (DK), the US Department of Labor LCA\n(H-1B) and PERM disclosure data, the Canadian positive LMIA employers list and the Irish employment\npermits issued to companies. GB, NL and DK are licences; US, CA and IE are **filing evidence**, not a\nlicence, and `kind` says which. A hit means the employer \"appears on the official register as of\" the\ndate given; it never means the employer will sponsor a given role. No JOA jobs are needed: the registers\nare read directly.\n\n**A name sent with its legal form names one legal entity.** When the name ends in a legal form (Ltd,\nLimited, plc, LLP, Inc, LLC, B.V., N.V., A/S, ApS and the like) it matches only the register entry that\nprints that name. Case, accents, punctuation, spacing, brackets, \"and\" and \"the\" do not count; Ltd is\nLimited, Inc is Incorporated, Corp is Corporation, \"Public Limited Company\" is plc. Every other word\ncounts: Group, Holdings, International, UK and country words make another name, and plc is not Ltd\n(\"Rolls-Royce Holdings plc\" is not \"Rolls-Royce plc\"; \"Barclays Bank UK PLC\" is not \"Barclays Bank\nPLC\"). The exact name matches also when entries close to it exist. An entry that is only close (a\ntwin) is never matched, with or without a town: it is listed in `possible_names` and `hint` says how\nit differs.\n\n**A name sent without a legal form** (\"Rolls-Royce\", \"Monzo Bank\", \"AstraZeneca\") is compared more\nloosely. The entry may print more than the name sent: a legal form, Group, Holding or Holdings,\nInternational, Co or Company, UK, US or USA, Canada, Ireland, Nederland or Netherlands, Danmark or\nDenmark at the end of its name, and text in brackets. It may not print less: a word of the name sent\nmust be in the entry (\"Rolls-Royce Holdings\" is not \"Rolls-Royce plc\"), except the register's own\ncountry. It is matched when exactly one register entry answers and the name is\ndistinctive (two or more words, or 10 or more characters). When the register prints exactly those\nwords as a whole name, that entry answers. When several entries answer (\"Kier\": \"Kier Ltd\" and \"Kier\nGroup plc\") the status is `ambiguous` with every one listed; the town picks one only when it is the\ntown of exactly one of them. A single word under 10 characters (\"Revolut\", \"IBM\") is `ambiguous`\n(`short_name`); it is matched with the entry's town, or when the register prints exactly that word as\na whole name, no other name on that country's registers contains it and the country was sent. On the\nDanish list a single word is matched at 0.75 (`name_country_weak`) when `country` is DK. A name the\nregister prints only as a trading name (\"t/a\", \"d/b/a\") is a candidate (`trading_name_only`) and\nmatches with the town. There is no fuzzy matching.\n\n**Hits.** One hit is one printed register name (one organisation number where the register prints\nnumbers); two entries are never merged. A name without a legal form that a register prints in several\ntowns is one hit per town. `match_type` is `exact_legal_name` when the name sent is the printed legal\nname word for word (accept these without a check) and `exact_normalised` when the names are equal once\nlegal forms and the words above are set aside (a match on a brand name: show `legal_name` or check it\nbefore you publish a claim). `matched_on` is `legal_name`, `trading_name` or `alias`. Methods:\n`name_town` (0.97: the town, and for the US the town and state, is the entry's), `name_region` (0.95,\nUS), `name_country` (0.92), `name_country_weak` (0.75, DK). The `statement` of a hit names the entry.\n\n**Another country.** A name that carries a country (UK, US, Canada, Ireland, Netherlands, Denmark, or\none in brackets) or the legal form of another country is never an entry of this register:\n\"AstraZeneca UK Limited\" is not \"AstraZeneca B.V.\" (NL), \"Foo GmbH\" is not \"Foo Ltd\" (GB). The status\nis `not_found`, the similar entry is in `possible_names` and `hint` says why.\n\n**Franchise brands and staffing firms.** A franchise brand (McDonald's, Tim Hortons, Subway, Home\nInstead and others, and any name 3 or more companies trade under on a register) is `excluded` in every\ncountry, with or without a town; `possible_names` lists register names that start with the brand.\nStaffing firms, recruiters and job boards are `excluded` (`staffing_or_recruiter`), every company of a\nstaffing group alike. A name of one character after normalisation is `name_too_short`.\n\n**NL aliases.** English names of Dutch universities, university medical centres, research institutes\nand public bodies (\"Eindhoven University of Technology\", \"University of Amsterdam\", \"Erasmus MC\")\nmap to the Dutch name the IND register prints, from a curated table: only when the name itself is on\nno register, only for NL (abbreviations such as TNO need `country: NL`), and only when the Dutch\nname is one organisation on the register. Such a hit says `matched_on: alias`.\n\n**Statuses.** `matched` (`matched: true`): JOA found the register entry that is this employer by its\nname. `ambiguous`: a register entry has this name, or contains it as whole words, or differs from it\nonly by a legal form or by a word such as Group, Holdings, International or UK, and JOA cannot confirm\nthat it is this employer; entries with the same name are in `hits` with `ambiguous: true` and a\nreason, the others are in `possible_names`, and `hits` can be empty. `not_found`: no entry of the\nregisters read has this name and none contains it (JOA reads a register for that country, or every\nregister when no country is sent). `excluded` (`reason`: `franchise_brand`, `staffing_or_recruiter`\nor `name_too_short`). `no_register`: JOA reads no register for that country, so this is not a no.\nExamples with country GB: \"Monzo\" is `ambiguous` with `possible_names` [\"Monzo Bank Ltd\"] and\n`suggested_name` \"Monzo Bank Ltd\"; \"Ocado\" is `ambiguous` with two `possible_names` and no\n`suggested_name`; \"Rolls-Royce Holdings plc\" is `ambiguous` with \"Rolls-Royce plc\" in\n`possible_names`, a `hint` that says it does not have Holdings, and no `suggested_name`; a made-up name\nis `not_found`; \"AstraZeneca UK Limited\" with country NL is `not_found` with \"AstraZeneca B.V.\" in\n`possible_names`.\n\n**`possible_names` and `suggested_name` are leads, never matches.** `possible_names`: up to 5 register\nnames, twins first, then names that contain the name sent as whole words, a name that starts with it\nfirst (\"Arup\" lists \"Ove Arup and Partners International Ltd\"). `suggested_name`: set when exactly\none register name is, or contains, the name sent and it was sent without a legal form (\"Monzo\" gives\n\"Monzo Bank Ltd\"); check that it is your employer, then send it as the name in a second call, which\nmatches. It is never set for a twin and never with more than one candidate. `hint` is one plain\nsentence on what to send next. Each country is decided on its own: `matched: true` means at least one\nhit is unambiguous.\n\n**One bad employer never fails the call.** Every employer is checked on its own. One that cannot be\nlooked up as sent (no name, a name over 300 characters, a country that is not two letters, a town or\nregion over 100 characters, an unknown field, a value that is not text) is answered in its place with\n`status: invalid`, the error code in `reason` (`missing_name`, `bad_name`, `bad_country`, `bad_place`,\n`bad_body`) and the problem in `hint`; the others are looked up and the call answers 200. Only a call\nin which no employer can be looked up is refused with 422 and the first employer's error. If JOA cannot\nlook up one employer this time, that one is answered `status: error` (`reason: lookup_failed`) and the\nothers are answered. A `region` is only used for the US and ignored elsewhere.\n\n**Price:** 0.1 record per employer looked up, rounded up per call (100 employers = 10 records, 7 = 1),\nwhatever the status; a repeated employer in one call is counted once; an employer answered `invalid`\nor `error` was not looked up and is not counted. Every plan, the free Explore plan included.\n`X-JOA-Records-Charged` says what was charged; the 15 minute repeat rule applies. No query parameters\n(400 `unknown_parameter`).\n\n**Legal note.** Every answer carries `legal_note_code` (`immigration_information`) and `legal_note` at\nthe top level. Register presence and any salary or rule comparison are information only: not\nimmigration or legal advice, not a service to candidates, and possibly incomplete, wrong or out of\ndate. Show the legal_note with this information, unless you are an authorised immigration adviser\npresenting it within your regulated service. If you omit it, you take full responsibility (Terms,\n\"Immigration and sponsor information\").\n",
        "operationId": "lookupSponsors",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "employers": [
                  {
                    "country": "GB",
                    "name": "Rolls-Royce",
                    "town": "Derby"
                  },
                  {
                    "country": "US",
                    "name": "Google",
                    "region": "CA",
                    "town": "Mountain View"
                  },
                  {
                    "country": "GB",
                    "name": "Home Instead"
                  }
                ]
              },
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "employers": {
                    "items": {
                      "$ref": "#/components/schemas/SponsorLookupInput"
                    },
                    "maxItems": 100,
                    "minItems": 1,
                    "type": "array"
                  }
                },
                "required": [
                  "employers"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/SponsorLookup"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/RecordQuotaExhausted"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Employer sponsor lookup, up to 100 employers per call",
        "tags": [
          "companies"
        ]
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "servers": [
    {
      "url": "https://api.jobopportunitiesapi.org"
    }
  ],
  "tags": [
    {
      "name": "jobs"
    },
    {
      "name": "companies"
    },
    {
      "name": "meta"
    },
    {
      "description": "Keyless, aggregate-only routes under /public/ (no rows, statistics only).\nMost of /public/* mirrors a keyed /v1 endpoint and is documented there;\nthe two BETA history routes below have no keyed twin and are documented\nhere in full. The rest of /public/* is documented at\nhttps://jobopportunitiesapi.org/docs/endpoints/public.\nThe four listing routes (/public/jobs, /public/jobs/{id}, /public/companies,\n/public/companies/{slug}) serve no rows to a caller: no key is **401**\n`key_required`; a usable key is **403** `listings_need_v1` (since 11 Nov 2026;\nit was 401); any other Authorization header is **401** `listings_need_v1`.\n",
      "name": "public"
    }
  ]
}