{
  "about": {
    "base_url": "https://api.jobopportunitiesapi.org",
    "caching": "Stable and versioned: help_version changes when the SHAPE of this document changes, grammar_version when the query grammar changes. Within a help_version every change is additive (new fields, new endpoints), so a cached copy stays usable. The response carries Cache-Control and ETag; send If-None-Match to check for a new one cheaply.",
    "content_type": "application/json; charset=utf-8",
    "read_me_first": "This document is the API describing itself: every endpoint, every parameter, the query grammar as it works today, the limits and quotas, the error codes and one worked example per endpoint. It is written for a program and readable by a person. The prose version lives at https://jobopportunitiesapi.org/docs; where they disagree this endpoint is the one that ships with the code.",
    "title": "Job Opportunities API: machine readable help",
    "website": "https://jobopportunitiesapi.org"
  },
  "authentication": {
    "applies_to": "every /v1 endpoint",
    "header": "Authorization: Bearer <key>",
    "keyless": "every other /public endpoint: the statistics, the documents and the mail links. /public/jobs, /public/jobs/{id}, /public/companies and /public/companies/{slug} serve the website's own pages only: they answer 403 listings_need_v1 to a usable key (401 listings_need_v1 to a key that is not usable) and 401 key_required without one, so read listings on /v1.",
    "note": "A refused request costs no records. Errors are JSON: {\"error\": \"<code>\", \"message\": \"<text>\"}. Branch on error, never on message.",
    "where_to_get_a_key": "https://jobopportunitiesapi.org/login (a free Explore key needs no card)"
  },
  "empty_search_hints": {
    "example": {
      "live_jobs": 37,
      "param": "city",
      "reason": "location_has_jobs",
      "text": "We have 37 live jobs in Newry (GB). None of them also matches your other filters.",
      "value": "Newry"
    },
    "reasons": {
      "city_unknown": "No live job has a city of that name (no spelling, any country).",
      "company_domain_unknown": "No company in our data has this website, read the way company_domain reads it (scheme, path and www. removed).",
      "country_not_covered": "No live job at all has this country. The countries we cover are listed at https://jobopportunitiesapi.org/coverage.",
      "date_window_narrow": "posted_after, verified_after or listed_after keeps only the last 7 days or less. Not given next to a finding that already explains the empty answer.",
      "location_empty": "The location parameters alone match no live job. Not given when the key is locked to a country.",
      "location_has_jobs": "The location parameters alone (city, country, country_match, state, region) match live jobs, counted up to 101 in live_jobs, and the other parameters removed them all.",
      "word_not_indexed": "A word of q is not in the search index."
    },
    "summary": "An empty first page of a live /v1/jobs search made with a key carries hints (since 12 Nov 2026): why nothing matched, one finding per item ({param, value, reason, live_jobs, text}). Never on a page with rows, a later page, a since poll, status=closed or any. Each finding says only what one quick check found at that moment; a check that fails or takes over 50 ms is left out, so hints can be absent even when a reason exists, and they never turn the answer into an error. Read reason, show text."
  },
  "endpoints": [
    {
      "auth": "key",
      "billing": "1 record per row returned, except a job already charged to your key in the last 24 hours (0 records), plus 1 for the include_total count when asked for.",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/jobs?country=DE&category=Engineering&limit=2\"",
      "group": "jobs",
      "method": "GET",
      "parameters": [
        "q",
        "title",
        "title_exclude",
        "company_name_contains",
        "description_contains",
        "country",
        "exclude_country",
        "state",
        "region",
        "city",
        "category",
        "family",
        "exclude_category",
        "company",
        "company_domain",
        "exclude_company_domain",
        "provider",
        "exclude_provider",
        "source_type",
        "exclude_source_type",
        "employment_type",
        "seniority",
        "remote",
        "remote_confirmed",
        "language",
        "language_exclude",
        "has_salary",
        "min_salary",
        "max_salary",
        "compensation_type",
        "exclude_compensation_type",
        "country_confidence",
        "require_fields",
        "has_description",
        "include_description",
        "include_poster_type",
        "quality",
        "status",
        "collapse",
        "max_per_company",
        "limit",
        "cursor",
        "include_total",
        "sort",
        "listed_after",
        "posted_after",
        "verified_after",
        "listed_before",
        "posted_before",
        "verified_before",
        "since",
        "country_match",
        "sponsor_register",
        "visa_text",
        "engagement",
        "contract_category",
        "agency",
        "working_schedule",
        "offset",
        "include"
      ],
      "path": "/v1/jobs",
      "summary": "List job rows, newest first, keyset paginated. This is the endpoint almost every integration uses. An empty first page says why in hints (see empty_search_hints)."
    },
    {
      "auth": "key",
      "billing": "1 record per row returned.",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/jobs/closed?closed_after=2026-10-01&limit=5\"",
      "group": "jobs",
      "method": "GET",
      "parameters": [
        "limit",
        "cursor",
        "closed_after",
        "closed_before",
        "closed_reason",
        "listed_after",
        "since",
        "country",
        "exclude_country",
        "category",
        "q",
        "title",
        "provider",
        "source_type",
        "company_domain"
      ],
      "path": "/v1/jobs/closed",
      "summary": "Roles that have come off their source, ordered by when they closed. Use it to mark a mirror stale."
    },
    {
      "auth": "key",
      "billing": "unmetered by design: ids only, no rows.",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/jobs/expired?since=2026-10-20T00:00:00Z&limit=100\"",
      "group": "jobs",
      "method": "GET",
      "parameters": [
        "since",
        "limit"
      ],
      "path": "/v1/jobs/expired",
      "summary": "The ids of roles that closed since a moment you give. Cheaper than /v1/jobs/closed for a deletion sweep."
    },
    {
      "auth": "key",
      "billing": "unmetered by design: ids only, no rows.",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/jobs/withdrawn?since=2026-11-07T00:00:00Z&limit=100\"",
      "group": "jobs",
      "method": "GET",
      "parameters": [
        "since",
        "country",
        "limit"
      ],
      "path": "/v1/jobs/withdrawn",
      "summary": "The ids of roles that left the served set WITHOUT closing (a hold, a quality rule, an employer withdrawal or opt-out, a licence removal) since a moment you give, with when they left and a reason category. The sibling of /v1/jobs/expired; together they cover every exit. With country (or a key country lock) it also lists, once, a job whose country changed away from your filter (most often our correction), with withdrawn_reason country_corrected."
    },
    {
      "auth": "key",
      "billing": "0.1 record per id checked, rounded up per call (1000 ids = 100 records, 7 ids = 1 record); every id counts whatever its status.",
      "example": "curl -s -X POST -H \"Authorization: Bearer $JOA_KEY\" -H 'Content-Type: application/json' --data '{\"ids\":[\"<uuid>\",\"<uuid>\"]}' \"https://api.jobopportunitiesapi.org/v1/jobs/status\"",
      "group": "jobs",
      "method": "POST",
      "parameters": [],
      "path": "/v1/jobs/status",
      "summary": "For a copy you keep: POST {\"ids\": [up to 1000 job ids]} and get each one's status (live, closed, withdrawn, unknown, exactly as GET /v1/jobs/{id} answers it), with closed_at/closed_reason, withdrawn_at/withdrawn_reason, content_version, content_changed_at and last_verified_at. Refetch only ids whose content_version differs from yours. Growth plan and above."
    },
    {
      "auth": "key",
      "billing": "1 record per row returned.",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/jobs/similar?job_id=<uuid>&country=US&limit=20\"",
      "group": "jobs",
      "method": "GET",
      "parameters": [
        "job_id",
        "min_score",
        "limit",
        "country",
        "category",
        "remote",
        "listed_after",
        "include",
        "include_description"
      ],
      "path": "/v1/jobs/similar",
      "summary": "Semantic search, more like this: the nearest served jobs to a job's stored vector (Qwen3-Embedding-8B, 1024 dims), with every /v1/jobs filter and a cosine similarity per row."
    },
    {
      "auth": "key",
      "billing": "1 record per row returned.",
      "example": "curl -s -X POST -H \"Authorization: Bearer $JOA_KEY\" -H 'Content-Type: application/json' --data @query.json \"https://api.jobopportunitiesapi.org/v1/jobs/similar?country=US&limit=20\"",
      "group": "jobs",
      "method": "POST",
      "parameters": [
        "min_score",
        "limit",
        "country",
        "category",
        "remote",
        "listed_after",
        "include",
        "include_description"
      ],
      "path": "/v1/jobs/similar",
      "summary": "Semantic search by vector: POST {\"vector\": [1024 numbers]} (a Qwen3-Embedding-8B query embedding with the documented instruction, first 1024 dims, unit length) or {\"job_id\": \"...\"}; filters and limit in the query string. Text queries answer 501 for now."
    },
    {
      "auth": "key",
      "billing": "1 record.",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/jobs/41737220-e01e-43d2-96b0-281b0906161d\"",
      "group": "jobs",
      "method": "GET",
      "parameters": [
        "id",
        "include_closed"
      ],
      "path": "/v1/jobs/{id}",
      "summary": "One job row by id. include_closed=true also resolves roles that have closed. The body is {\"data\": {...job...}, \"description\": \"...\"}: the advert text is inside data (data.description, since 11 Nov 2026, omitted when the row has none) and the same value, after the same redaction, also sits beside data (kept for compatibility; null when the row has none). Read data.description."
    },
    {
      "auth": "key",
      "billing": "1 record per row returned.",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/companies?country=DE&limit=5\"",
      "group": "companies",
      "method": "GET",
      "parameters": [
        "q",
        "country",
        "org_type",
        "source_type",
        "has_website",
        "include_discovered",
        "limit",
        "offset",
        "cursor"
      ],
      "path": "/v1/companies",
      "summary": "The employer directory: one row per company, with its open-role count."
    },
    {
      "auth": "key",
      "billing": "1 record.",
      "example": "curl -s -L -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/companies/but\"",
      "group": "companies",
      "method": "GET",
      "parameters": [
        "slug"
      ],
      "path": "/v1/companies/{slug}",
      "summary": "One employer by slug. A retired slug answers a 301 to its replacement, so follow redirects."
    },
    {
      "auth": "key",
      "billing": "0.1 record per employer, rounded up per call: 1 record per GET. Every plan, free included.",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/sponsors/lookup?name=Rolls-Royce&country=GB&town=Derby\"",
      "group": "companies",
      "method": "GET",
      "parameters": [
        "name",
        "country",
        "town",
        "region"
      ],
      "path": "/v1/sponsors/lookup",
      "summary": "Is this employer on an official sponsor register? One employer by name (optional country, town, region), with or without JOA jobs. Registers: UK Home Office licensed sponsors (GB), IND recognised sponsors (NL), SIRI fast-track (DK) are licences; US DOL LCA and PERM, Canadian LMIA and Irish employment permits (US, CA, IE) are filing evidence. Answers matched (JOA found the register entry that is this employer by its name), ambiguous (a register entry has this name, contains it as whole words, or differs from it only by a legal form or a word such as Group, Holdings, International or UK, and JOA cannot confirm it is this employer: same-name entries are in hits with ambiguous true, the others in possible_names, and hits can be empty; never a silent pick), not_found (no entry of the registers read has this name and none contains it), excluded (franchise brand, staffing firm, short name) or no_register (JOA reads no register for that country, so this is not a no). A name sent with its legal form matches only the entry that prints that name: Group, Holdings, International, UK and country words count and plc is not Ltd (Rolls-Royce Holdings plc is not Rolls-Royce plc); such a twin is listed in possible_names with a hint, never matched, with or without a town. A name sent without a legal form is compared more loosely and matches when exactly one entry answers and the name has two or more words or 10 or more characters; a single shorter word is ambiguous until you add the town. One hit is one printed register name, never two merged, and its statement names the entry. match_type is exact_legal_name (the name sent is the printed legal name word for word: accept without a check) or exact_normalised (equal once legal forms and words such as Group or UK are set aside: a match on a brand name, show legal_name or check it); matched_on is legal_name, trading_name or alias. There is no fuzzy matching. A name of another country or with a foreign legal form is not_found with the similar entry in possible_names (AstraZeneca UK Limited is not AstraZeneca B.V.). English names of Dutch institutions (Eindhoven University of Technology) map to the IND register name from a curated table (matched_on alias). possible_names and suggested_name are leads, never matches: suggested_name is set when exactly one register name is, or contains, the name sent without a legal form (Monzo gives Monzo Bank Ltd); check it, then send it as the name in a second call. hint says what to send next. A hit means the employer appears on the official register as of a date, never that it will sponsor. Every answer carries legal_note_code and legal_note at the top level (immigration_information): this is information only, not immigration or legal advice. Show the legal_note with this information, unless you are an authorised immigration adviser presenting it within your regulated service. If you omit it, you take full responsibility."
    },
    {
      "auth": "key",
      "billing": "0.1 record per employer looked up, rounded up per call (100 employers = 10 records); every employer looked up counts whatever the answer; a repeated employer in one call counts once; an employer answered invalid or error was not looked up and is not counted. Every plan, free included.",
      "example": "curl -s -X POST -H \"Authorization: Bearer $JOA_KEY\" -H 'Content-Type: application/json' --data '{\"employers\":[{\"name\":\"Rolls-Royce\",\"country\":\"GB\",\"town\":\"Derby\"},{\"name\":\"Google\",\"country\":\"US\",\"town\":\"Mountain View\",\"region\":\"CA\"}]}' \"https://api.jobopportunitiesapi.org/v1/sponsors/lookup\"",
      "group": "companies",
      "method": "POST",
      "parameters": [],
      "path": "/v1/sponsors/lookup",
      "summary": "The employer sponsor lookup for up to 100 employers per call: POST {\"employers\": [{\"name\": ..., \"country\": ..., \"town\": ..., \"region\": ...}]}. One result per employer, in order, with each register hit (register, country, kind, routes, legal and trading name, towns, as_of date, source link, matched_on (legal_name, trading_name or alias), match_type (exact_legal_name or exact_normalised), match method, confidence, ambiguous flag, a statement that names the entry), possible_names and suggested_name (leads, never matches: check suggested_name, then send it as the name in a second call) and a plain hint on what to send next. The statuses and the matching rules are those of GET /v1/sponsors/lookup. One bad employer never fails the call: each is checked on its own, and one that cannot be looked up as sent (no name, a bad country, an unknown field) is answered in its place with status invalid, the error code in reason and the problem in hint, while the others are looked up; only a call in which no employer can be looked up is a 422. status error (reason lookup_failed) means JOA could not look up that one employer this time. region is only used for the US and ignored for other countries. Every answer carries legal_note_code and legal_note at the top level (immigration_information): this is information only, not immigration or legal advice. Show the legal_note with this information, unless you are an authorised immigration adviser presenting it within your regulated service. If you omit it, you take full responsibility."
    },
    {
      "auth": "key",
      "billing": "1 record per event returned; correction events cost nothing.",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/changes?since=2026-10-24T00:00:00Z&limit=100\"",
      "group": "delta",
      "method": "GET",
      "parameters": [
        "since",
        "country",
        "limit"
      ],
      "path": "/v1/changes",
      "summary": "The delta feed: created, updated, withdrawn and delisted events for the served set, resumable by cursor. With country (or a key country lock), a job whose country changed away from your filter (most often our correction) arrives once as a free withdrawn (correction true)."
    },
    {
      "auth": "key",
      "billing": "1 record per row written.",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/export?country=LI\"",
      "group": "delta",
      "method": "GET",
      "parameters": [
        "after",
        "status",
        "q",
        "title",
        "title_exclude",
        "company_name_contains",
        "description_contains",
        "country",
        "exclude_country",
        "category",
        "family",
        "provider",
        "source_type",
        "company_domain",
        "employment_type",
        "seniority",
        "remote",
        "has_salary",
        "min_salary",
        "max_salary",
        "require_fields",
        "listed_after",
        "posted_after"
      ],
      "path": "/v1/export",
      "summary": "Streams every matching row as NDJSON, ordered by id, resumable with after=. Charges as it writes."
    },
    {
      "auth": "key",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/export-packs\"",
      "group": "delta",
      "method": "GET",
      "parameters": [],
      "path": "/v1/export-packs",
      "summary": "List the export packs this key has requested and their state."
    },
    {
      "auth": "key",
      "example": "curl -s -X POST -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/export-packs?country=LI&format=ndjson\"",
      "group": "delta",
      "method": "POST",
      "parameters": [],
      "path": "/v1/export-packs",
      "summary": "Request a bulk export pack; it is built in the background and downloads as one file."
    },
    {
      "auth": "key",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/export-packs/<id>\"",
      "group": "delta",
      "method": "GET",
      "parameters": [
        "id"
      ],
      "path": "/v1/export-packs/{id}",
      "summary": "One export pack: state, row count and its signed download link."
    },
    {
      "auth": "key",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/meta/facets\"",
      "group": "meta",
      "method": "GET",
      "parameters": [],
      "path": "/v1/meta/facets",
      "summary": "The controlled vocabularies (category, seniority, employment_type and the rest) with counts."
    },
    {
      "auth": "key",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/meta/providers\"",
      "group": "meta",
      "method": "GET",
      "parameters": [],
      "path": "/v1/meta/providers",
      "summary": "The provider vocabulary: every source we serve rows from, with row counts."
    },
    {
      "auth": "key",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/meta/freshness\"",
      "group": "meta",
      "method": "GET",
      "parameters": [],
      "path": "/v1/meta/freshness",
      "summary": "How fresh the ledger is: how much was verified when, and how stale it reads."
    },
    {
      "auth": "key",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/me\"",
      "group": "account",
      "method": "GET",
      "parameters": [],
      "path": "/v1/me",
      "summary": "This key: plan, allowance, renewal and country lock."
    },
    {
      "auth": "key",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/me/usage?days=30\"",
      "group": "account",
      "method": "GET",
      "parameters": [
        "metric",
        "days"
      ],
      "path": "/v1/me/usage",
      "summary": "Records used per day for this key."
    },
    {
      "auth": "key",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/me/export-estimate?country=DE\"",
      "group": "account",
      "method": "GET",
      "parameters": [
        "country",
        "category",
        "q",
        "title",
        "require_fields",
        "has_salary"
      ],
      "path": "/v1/me/export-estimate",
      "summary": "What an export of these filters would cost, before you run it. Unmetered. remaining_this_month is -1 on a key with no monthly record allowance; remaining_unlimited (since 11 Nov 2026) is true exactly then."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/v1/openapi.yaml\"",
      "group": "docs",
      "method": "GET",
      "parameters": [],
      "path": "/v1/openapi.yaml",
      "summary": "The OpenAPI 3.1 contract of the API, rendered from the running build."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/v1/openapi.json\"",
      "group": "docs",
      "method": "GET",
      "parameters": [],
      "path": "/v1/openapi.json",
      "summary": "The same contract as JSON."
    },
    {
      "auth": "key",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/help\"",
      "group": "docs",
      "method": "GET",
      "parameters": [],
      "path": "/v1/help",
      "summary": "This document. Also served keyless at /public/help."
    },
    {
      "auth": "website server only",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/jobs?country=DE&limit=2\"",
      "group": "public-listings",
      "method": "GET",
      "parameters": [],
      "path": "/public/jobs",
      "summary": "Reserved for the website's own pages. It no longer serves listing rows to anyone else: with a usable key it answers 403 listings_need_v1 (401 listings_need_v1 for a key that is not usable), without one 401 key_required. Use GET /v1/jobs."
    },
    {
      "auth": "website server only",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/jobs/41737220-e01e-43d2-96b0-281b0906161d\"",
      "group": "public-listings",
      "method": "GET",
      "parameters": [],
      "path": "/public/jobs/{id}",
      "summary": "Reserved for the website's own pages. It no longer serves listing rows to anyone else: with a usable key it answers 403 listings_need_v1 (401 listings_need_v1 for a key that is not usable), without one 401 key_required. Use GET /v1/jobs/{id}."
    },
    {
      "auth": "website server only",
      "example": "curl -s -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/companies?country=DE&limit=5\"",
      "group": "public-listings",
      "method": "GET",
      "parameters": [],
      "path": "/public/companies",
      "summary": "Reserved for the website's own pages. It no longer serves listing rows to anyone else: with a usable key it answers 403 listings_need_v1 (401 listings_need_v1 for a key that is not usable), without one 401 key_required. Use GET /v1/companies."
    },
    {
      "auth": "website server only",
      "example": "curl -s -L -H \"Authorization: Bearer $JOA_KEY\" \"https://api.jobopportunitiesapi.org/v1/companies/but\"",
      "group": "public-listings",
      "method": "GET",
      "parameters": [],
      "path": "/public/companies/{slug}",
      "summary": "Reserved for the website's own pages. It no longer serves listing rows to anyone else: with a usable key it answers 403 listings_need_v1 (401 listings_need_v1 for a key that is not usable), without one 401 key_required. Use GET /v1/companies/{slug}."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/companies/but/open-roles-history?days=90\"",
      "group": "public-listings",
      "method": "GET",
      "parameters": [
        "slug",
        "days"
      ],
      "path": "/public/companies/{slug}/open-roles-history",
      "summary": "How many roles an employer had open, day by day."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/facets\"",
      "group": "statistics",
      "method": "GET",
      "parameters": [],
      "path": "/public/facets",
      "summary": "Facet chips and counts for the public ledger."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/providers\"",
      "group": "statistics",
      "method": "GET",
      "parameters": [],
      "path": "/public/providers",
      "summary": "Providers with served rows, with counts and generated_at."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/freshness\"",
      "group": "statistics",
      "method": "GET",
      "parameters": [],
      "path": "/public/freshness",
      "summary": "Verification freshness of the public ledger."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/coverage\"",
      "group": "statistics",
      "method": "GET",
      "parameters": [],
      "path": "/public/coverage",
      "summary": "Coverage report: live rows, employers, page-verified share, per-country table."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/coverage/countries\"",
      "group": "statistics",
      "method": "GET",
      "parameters": [],
      "path": "/public/coverage/countries",
      "summary": "The per-country coverage table."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/coverage/employers\"",
      "group": "statistics",
      "method": "GET",
      "parameters": [],
      "path": "/public/coverage/employers",
      "summary": "Coverage by employer: how much of an employer's own openings we carry."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/stats\"",
      "group": "statistics",
      "method": "GET",
      "parameters": [],
      "path": "/public/stats",
      "summary": "Headline numbers for the site."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/site-stats\"",
      "group": "statistics",
      "method": "GET",
      "parameters": [],
      "path": "/public/site-stats",
      "summary": "The site statistics block, with its window and stale flag."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/market-signals?country=DE&family=healthcare\"",
      "group": "statistics",
      "method": "GET",
      "parameters": [
        "family",
        "country",
        "seniority"
      ],
      "path": "/public/market-signals",
      "summary": "Hiring market signals: pay percentiles and time-to-fill per segment or company."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/market-signals/history?country=DE&family=healthcare&days=90\"",
      "group": "statistics",
      "method": "GET",
      "parameters": [
        "family",
        "country",
        "seniority",
        "days"
      ],
      "path": "/public/market-signals/history",
      "summary": "The same signals over time."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/geo\"",
      "group": "statistics",
      "method": "GET",
      "parameters": [],
      "path": "/public/geo",
      "summary": "Which country the checkout should preselect for you. Advisory only."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/plans\"",
      "group": "statistics",
      "method": "GET",
      "parameters": [],
      "path": "/public/plans",
      "summary": "Plans, prices and allowances as the pricing page shows them."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/status\"",
      "group": "statistics",
      "method": "GET",
      "parameters": [],
      "path": "/public/status",
      "summary": "Service status of the API."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/quote?plan=signal&country=DE\"",
      "group": "statistics",
      "method": "GET",
      "parameters": [
        "plan",
        "country",
        "vat_number"
      ],
      "path": "/public/quote",
      "summary": "What a plan costs this customer, from the same tax table that charges them."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/launch-offer\"",
      "group": "statistics",
      "method": "GET",
      "parameters": [],
      "path": "/public/launch-offer",
      "summary": "The currently active discount code, its percent and end date."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/house-ad\"",
      "group": "statistics",
      "method": "GET",
      "parameters": [],
      "path": "/public/house-ad",
      "summary": "The house ad slot shown in the browse list."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/sitemap-meta\"",
      "group": "statistics",
      "method": "GET",
      "parameters": [],
      "path": "/public/sitemap-meta",
      "summary": "Counts behind the sitemap chunks."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/sitemap/jobs/1\"",
      "group": "statistics",
      "method": "GET",
      "parameters": [
        "kind",
        "page"
      ],
      "path": "/public/sitemap/{kind}/{page}",
      "summary": "One sitemap chunk."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/health\"",
      "group": "docs",
      "method": "GET",
      "parameters": [],
      "path": "/health",
      "summary": "Liveness probe of the API process."
    },
    {
      "auth": "none",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"email\":\"you@example.com\"}' \"https://api.jobopportunitiesapi.org/public/auth/request\"",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/request",
      "summary": "Start a sign-in: mails a one-time link to the address."
    },
    {
      "auth": "signed token",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"email\":\"you@example.com\",\"token\":\"<from the mail>\"}' \"https://api.jobopportunitiesapi.org/public/auth/verify\"",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/verify",
      "summary": "Complete a sign-in with the token from the mail."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/whoami\"",
      "group": "account",
      "method": "GET",
      "parameters": [],
      "path": "/public/auth/whoami",
      "summary": "Who the browser session belongs to."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/signout-all\"",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/signout-all",
      "summary": "End every session of this account."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/keys\"",
      "group": "account",
      "method": "GET",
      "parameters": [],
      "path": "/public/auth/keys",
      "summary": "This account's API keys."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{\"name\":\"my integration\"}' \"https://api.jobopportunitiesapi.org/public/auth/keys\"",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/keys",
      "summary": "Create a free Explore key. No trial starts; a company email address gets its first month of Starter or Growth free at checkout."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/keys/<id>/usage\"",
      "group": "account",
      "method": "GET",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/keys/{id}/usage",
      "summary": "Usage of one key."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{\"name\":\"new name\"}' \"https://api.jobopportunitiesapi.org/public/auth/keys/<id>/name\"",
      "group": "account",
      "method": "POST",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/keys/{id}/name",
      "summary": "Rename a key."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{\"endpoints\":[\"/v1/jobs\",\"/v1/changes\"]}' \"https://api.jobopportunitiesapi.org/public/auth/keys/<id>/endpoints\" responds {\"status\":\"ok\",\"endpoints\":[\"/v1/jobs\",\"/v1/changes\"]}",
      "group": "account",
      "method": "POST",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/keys/{id}/endpoints",
      "summary": "Choose which endpoints one of your keys may call. An empty list gives it every endpoint its plan allows; only the endpoint ids of GET /public/auth/keys are accepted."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/keys/<id>/revoke\"",
      "group": "account",
      "method": "POST",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/keys/{id}/revoke",
      "summary": "Revoke a key."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/keys/<id>/rotate\"",
      "group": "account",
      "method": "POST",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/keys/{id}/rotate",
      "summary": "Rotate a key's secret."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/keys/<id>/cancel\"",
      "group": "account",
      "method": "POST",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/keys/{id}/cancel",
      "summary": "Cancel the subscription on a key."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/keys/<id>/resume\"",
      "group": "account",
      "method": "POST",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/keys/{id}/resume",
      "summary": "Resume a cancelled subscription."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/keys/<id>/billing-portal\"",
      "group": "account",
      "method": "POST",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/keys/{id}/billing-portal",
      "summary": "Open the merchant's billing portal for this key."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{\"ref\":\"limit_console\",\"plan\":\"growth\"}' \"https://api.jobopportunitiesapi.org/public/auth/keys/<id>/upgrade-link\" responds {\"url\":\"<the signed one-click link>\",\"fallback\":\"/checkout?plan=growth&key=<id>&ref=limit_console\",\"eligible\":true,\"reason\":\"\"}",
      "group": "account",
      "method": "POST",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/keys/{id}/upgrade-link",
      "summary": "Build the signed one-click upgrade link for one of your keys. url is null with a reason when one-click does not cover this key or plan, and fallback is always the checkout page."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{\"country\":\"DE\",\"q\":\"nurse\"}' \"https://api.jobopportunitiesapi.org/public/auth/keys/<id>/try\" responds the /v1/jobs body, e.g. {\"data\":[{\"id\":\"<job id>\",\"title\":\"Registered Nurse\",\"company\":\"...\"}],\"next_cursor\":null,\"has_more\":false}",
      "group": "account",
      "method": "POST",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/keys/{id}/try",
      "summary": "Run the tutorial's test query for this key: the real GET /v1/jobs answer with limit 5, metered like a real call, at most 20 runs a day. Answers carry X-JOA-Test-Run: 1."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/keys/<id>/trial\" responds {\"state\":\"eligible\",\"reason\":\"\",\"offer\":{\"plan\":\"growth\",\"plan_name\":\"Growth\",\"days\":14},\"trial\":null}",
      "group": "account",
      "method": "GET",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/keys/{id}/trial",
      "summary": "The trial this key already has, if any. state is on_trial, not_eligible, paid or ended. New trials are retired since 1 November 2026 (reason trial_retired): the first month free is applied at checkout instead."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{}' \"https://api.jobopportunitiesapi.org/public/auth/keys/<id>/trial\" responds {\"state\":\"on_trial\",\"reason\":\"\",\"offer\":null,\"trial\":{\"plan\":\"growth\",\"plan_name\":\"Growth\",\"ends\":\"2026-11-10\",\"days\":14,\"days_left\":14,\"source\":\"self\"},\"started\":true}",
      "group": "account",
      "method": "POST",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/keys/{id}/trial",
      "summary": "Retired since 1 November 2026: no new trial starts, the answer is 409 not_eligible with reason trial_retired. A trial that is already running is returned unchanged, with started false."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/keys/<id>/recommendation\" responds {\"key_id\":\"<id>\",\"current_plan\":\"explore\",\"plan\":\"growth\",\"reason\":\"<why this plan fits>\",\"fast_days\":null,\"projected\":null,\"trial_had_change_feed\":false,\"move_in_place\":false}",
      "group": "account",
      "method": "GET",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/keys/{id}/recommendation",
      "summary": "The plan this key's usage points at, with the reason and the numbers behind it."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/keys/<id>/upgrade-now\" responds {\"key_id\":\"<id>\",\"plan\":\"explore\",\"plan_name\":\"Explore\",\"used\":920,\"limit\":1000,\"pct\":92,\"show\":true,\"target_plan\":\"starter\",\"target_name\":\"Starter\",\"target_price_cents\":2900,\"target_records\":10000,\"action\":\"one_click\",\"personal_offer\":null,\"usage_offer\":null}",
      "group": "account",
      "method": "GET",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/keys/{id}/upgrade-now",
      "summary": "What the Upgrade now button under the usage meter shows for this key: the month's use against its allowance, whether it is above 85 per cent, the plan it would move to and how (a personal offer link, the one-click same-key checkout, a move in place, or a note to write to us), and any personal or first 75 per cent offer that applies. Read only: the link itself is minted at the click by POST /public/auth/keys/{id}/upgrade-link with ref upgrade_now."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/heard-from\" responds {\"ask\":true,\"options\":[{\"code\":\"google_search\",\"label\":\"Google search\"}]}",
      "group": "account",
      "method": "GET",
      "parameters": [],
      "path": "/public/auth/heard-from",
      "summary": "Whether to ask this account \"How did you find us?\" (it has a key, none of its keys carries an answer, and it has not answered or dismissed), with the answer options."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{\"heard_from\":\"github\"}' \"https://api.jobopportunitiesapi.org/public/auth/heard-from\" responds {\"ok\":true,\"keys_updated\":1}",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/heard-from",
      "summary": "Answer \"How did you find us?\" (heard_from, and heard_from_text up to 100 characters with other) or dismiss the prompt (dismiss true). The answer is stored on every key of the account that has none and never overwrites an earlier one. 422 bad_heard_from for an unknown answer."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/console\" responds {\"console_v2\":true,\"mode\":\"pilot\",\"reason\":\"<reason code>\",\"override\":null,\"can_opt_out\":true,\"onboarding\":{\"path\":\"code\",\"trial_step\":null,\"skipped_at\":null,\"finished_at\":null},\"first_seen_at\":\"2026-10-27T09:00:00Z\"}",
      "group": "account",
      "method": "GET",
      "parameters": [],
      "path": "/public/auth/console",
      "summary": "The console switch result for this account and its onboarding state. The first call records the account's cohort."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{\"onboarding_path\":\"code\",\"onboarding\":\"finish\"}' \"https://api.jobopportunitiesapi.org/public/auth/console\" responds {\"console_v2\":true,\"mode\":\"pilot\",\"reason\":\"<reason code>\",\"override\":null,\"can_opt_out\":true,\"onboarding\":{\"path\":\"code\",\"trial_step\":null,\"skipped_at\":null,\"finished_at\":\"2026-10-27T09:05:00Z\"},\"first_seen_at\":\"2026-10-27T09:00:00Z\"}",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/console",
      "summary": "Change this account's console state: onboarding_path (code, nocode, ai), onboarding (skip, finish, reset), trial (skip) and override (on, off, clear). Answers with the GET shape."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{\"events\":[{\"name\":\"page_viewed\",\"props\":{\"page\":\"/dashboard\"}}]}' \"https://api.jobopportunitiesapi.org/public/auth/console/events\" responds 204 No Content",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/console/events",
      "summary": "Browser-only funnel events, at most 20 a call. Unknown names and props are dropped silently and the answer is 204 No Content; 120 events an hour per account."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{\"topic\":\"data\",\"message\":\"Where does the country field come from?\",\"include_context\":true}' \"https://api.jobopportunitiesapi.org/public/auth/support\" responds {\"status\":\"received\",\"id\":\"<id>\",\"topic\":\"data\",\"email\":\"you@example.com\",\"created_at\":\"2026-10-27T09:00:00Z\"}",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/support",
      "summary": "Send a signed-in support message (topic support, data, billing, build, other or limit). It is stored and mailed; include_context adds the account's plan and usage. At most 5 an hour."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/support\" responds {\"messages\":[{\"id\":\"<id>\",\"topic\":\"data\",\"topic_name\":\"A question about the data\",\"first_line\":\"Where does the country field come from?\",\"created_at\":\"2026-10-27T09:00:00Z\",\"status\":\"sent\"}]}",
      "group": "account",
      "method": "GET",
      "parameters": [],
      "path": "/public/auth/support",
      "summary": "This account's messages, newest first, at most 50: topic, first line, date and whether it was handled."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{\"kind\":\"connector\",\"tool\":\"Airbyte\",\"text\":\"We would sync new rows nightly.\"}' \"https://api.jobopportunitiesapi.org/public/auth/feedback\" responds 201 {\"ok\":true}",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/feedback",
      "summary": "Ask for a connector (kind connector, the tool's name and the use case). It becomes a roadmap proposal. At most 10 a day per account."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/account/deletion\" responds {\"state\":\"none\",\"keys\":[{\"id\":\"<id>\",\"prefix\":\"joa_1a2b3c4d\",\"name\":\"my integration\",\"plan\":\"explore\",\"status\":\"active\",\"billing\":\"none\",\"cancelled_in_period\":false,\"paid_no_gate\":false,\"lifetime\":false,\"key_left\":true,\"billing_live\":false}],\"keys_left\":true,\"paid_live\":false,\"scheduled_for\":null}",
      "group": "account",
      "method": "GET",
      "parameters": [],
      "path": "/public/auth/account/deletion",
      "summary": "Where this account's deletion stands: state (none, requested, scheduled, running or held), the keys that still block step 1, and the scheduled time."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{\"phrase\":\"Delete Everything\"}' \"https://api.jobopportunitiesapi.org/public/auth/account/deletion\" responds 202 {\"state\":\"requested\"}",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/account/deletion",
      "summary": "Ask for the deletion link: send the exact phrase Delete Everything. A mail carries the confirm link, and the deletion is scheduled only when that link is used."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{}' \"https://api.jobopportunitiesapi.org/public/auth/account/deletion/cancel\" responds {\"state\":\"cancelled\"}",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/account/deletion/cancel",
      "summary": "Cancel this account's scheduled deletion before it runs. The mailed link has its own route below."
    },
    {
      "auth": "signed token",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"token\":\"<from the mail>\"}' \"https://api.jobopportunitiesapi.org/public/account/deletion/peek\" responds {\"kind\":\"confirm\",\"email\":\"you@example.com\",\"scheduled_for\":null}",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/account/deletion/peek",
      "summary": "What a deletion mail's token stands for (confirm or cancel), the address it was sent to and the scheduled time. Never consumes the token."
    },
    {
      "auth": "signed token",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"token\":\"<from the mail>\"}' \"https://api.jobopportunitiesapi.org/public/account/deletion/confirm\" responds {\"state\":\"scheduled\",\"scheduled_for\":\"2026-11-03T09:00:00Z\"}",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/account/deletion/confirm",
      "summary": "Confirm the deletion with the token from the mail: the account is scheduled, and a second mail carries the cancel link."
    },
    {
      "auth": "signed token",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"token\":\"<from the mail>\"}' \"https://api.jobopportunitiesapi.org/public/account/deletion/cancel\" responds {\"state\":\"cancelled\"}",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/account/deletion/cancel",
      "summary": "Cancel the scheduled deletion with the cancel token from the second mail."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/saved-searches\"",
      "group": "account",
      "method": "GET",
      "parameters": [],
      "path": "/public/auth/saved-searches",
      "summary": "List your saved searches with their filters."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{}' \"https://api.jobopportunitiesapi.org/public/auth/saved-searches\"",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/saved-searches",
      "summary": "Create a saved search with its filters."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X DELETE -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/saved-searches/<id>\"",
      "group": "account",
      "method": "DELETE",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/saved-searches/{id}",
      "summary": "Delete a saved search with its filters."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/saved-searches/<id>/viewed\" responds {\"status\":\"saved\",\"last_viewed_at\":\"2026-10-27T09:00:00Z\"}",
      "group": "account",
      "method": "POST",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/saved-searches/{id}/viewed",
      "summary": "Mark a saved search as looked at now: that moment becomes the baseline of its new since last look delta."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/watches\"",
      "group": "account",
      "method": "GET",
      "parameters": [],
      "path": "/public/auth/watches",
      "summary": "List the jobs you watch."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{}' \"https://api.jobopportunitiesapi.org/public/auth/watches\"",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/watches",
      "summary": "Create a job you watch."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X DELETE -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/watches/<id>\"",
      "group": "account",
      "method": "DELETE",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/watches/{id}",
      "summary": "Delete a job you watch."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/watches/lists\" responds {\"lists\":[{\"id\":\"<id>\",\"name\":\"Sent to Johan\",\"jobs\":[{\"id\":\"<job id>\",\"title\":\"Registered Nurse\",\"company\":\"...\"}],\"created_at\":\"2026-10-27T09:00:00Z\",\"updated_at\":\"2026-10-27T09:00:00Z\"}],\"limits\":{\"notes\":500,\"note_length\":2000,\"saved_searches\":50,\"saved_lists\":50,\"jobs_per_list\":200}}",
      "group": "account",
      "method": "GET",
      "parameters": [],
      "path": "/public/auth/watches/lists",
      "summary": "Your saved lists (named sets of job ids), each job resolved to a title and a company where the ledger still has it. The caps ride along in limits."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{\"name\":\"Sent to Johan\",\"job_ids\":[\"<job id>\"]}' \"https://api.jobopportunitiesapi.org/public/auth/watches/lists\" responds 201 {\"status\":\"saved\",\"id\":\"<id>\"}",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/watches/lists",
      "summary": "Make a saved list (201) or re-save one (200, with its id): the name and the whole job set are written each time. Up to 50 lists of 200 jobs, one name per account."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X DELETE -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/watches/lists/<id>\" responds {\"status\":\"deleted\"}",
      "group": "account",
      "method": "DELETE",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/watches/lists/{id}",
      "summary": "Delete a saved list and the one note hanging on it."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/alerts\"",
      "group": "account",
      "method": "GET",
      "parameters": [],
      "path": "/public/auth/alerts",
      "summary": "List your alerts on saved searches."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{}' \"https://api.jobopportunitiesapi.org/public/auth/alerts\"",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/alerts",
      "summary": "Create an alert on a saved search."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X DELETE -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/alerts/<id>\"",
      "group": "account",
      "method": "DELETE",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/alerts/{id}",
      "summary": "Delete an alert on a saved search."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/saved-searches/<id>/alert\"",
      "group": "account",
      "method": "POST",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/saved-searches/{id}/alert",
      "summary": "Turn an email alert on or off for a saved search."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/notes?job_id=<job id>\" responds {\"notes\":[{\"id\":\"<id>\",\"job_id\":\"<job id>\",\"list_id\":null,\"text\":\"Call them about the visa.\",\"pinned\":true,\"created_at\":\"2026-10-27T09:00:00Z\",\"updated_at\":\"2026-10-27T09:00:00Z\"}],\"limits\":{\"notes\":500,\"note_length\":2000,\"saved_searches\":50,\"saved_lists\":50,\"jobs_per_list\":200}}",
      "group": "account",
      "method": "GET",
      "parameters": [],
      "path": "/public/auth/notes",
      "summary": "Your margin notes on one job or one saved list, pinned first and newest next. job_id or list_id narrows to one target; the caps ride along in limits."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{\"job_id\":\"<job id>\",\"text\":\"Call them about the visa.\",\"pinned\":true}' \"https://api.jobopportunitiesapi.org/public/auth/notes\" responds {\"status\":\"saved\",\"id\":\"<id>\"}",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/notes",
      "summary": "Save the one note on a job or on a saved list (job_id or list_id, never both). Saving again re-saves it. Up to 500 notes of 2,000 characters."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X DELETE -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/notes/<id>\" responds {\"status\":\"deleted\"}",
      "group": "account",
      "method": "DELETE",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/notes/{id}",
      "summary": "Delete one note by its own id."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/export-log\"",
      "group": "account",
      "method": "GET",
      "parameters": [],
      "path": "/public/auth/export-log",
      "summary": "The exports this account has run."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{\"note\":\"sync\"}' \"https://api.jobopportunitiesapi.org/public/auth/export-log\"",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/export-log",
      "summary": "Record an export the account ran."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X DELETE -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/export-log/<id>\" responds {\"status\":\"deleted\"}",
      "group": "account",
      "method": "DELETE",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/export-log/{id}",
      "summary": "Remove one row of your own export history."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/request-log\"",
      "group": "account",
      "method": "GET",
      "parameters": [],
      "path": "/public/auth/request-log",
      "summary": "What this account's keys have requested recently."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/lifecycle-emails\"",
      "group": "account",
      "method": "GET",
      "parameters": [],
      "path": "/public/auth/lifecycle-emails",
      "summary": "Which product emails this address receives."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{\"weekly\":false}' \"https://api.jobopportunitiesapi.org/public/auth/lifecycle-emails\"",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/lifecycle-emails",
      "summary": "Change which product emails this address receives."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/jobs?country=DE&limit=2\" responds {\"data\":[{\"id\":\"<job id>\",\"title\":\"Registered Nurse\",\"company\":\"...\",\"country\":\"DE\"}],\"next_cursor\":null,\"has_more\":false}",
      "group": "account",
      "method": "GET",
      "parameters": [
        "q",
        "title",
        "title_exclude",
        "company_name_contains",
        "description_contains",
        "country",
        "exclude_country",
        "state",
        "region",
        "city",
        "category",
        "family",
        "exclude_category",
        "company",
        "company_domain",
        "exclude_company_domain",
        "provider",
        "exclude_provider",
        "source_type",
        "exclude_source_type",
        "employment_type",
        "seniority",
        "remote",
        "remote_confirmed",
        "language",
        "language_exclude",
        "has_salary",
        "min_salary",
        "max_salary",
        "compensation_type",
        "exclude_compensation_type",
        "country_confidence",
        "require_fields",
        "has_description",
        "include_description",
        "include_poster_type",
        "quality",
        "status",
        "collapse",
        "max_per_company",
        "limit",
        "cursor",
        "include_total",
        "sort",
        "listed_after",
        "posted_after",
        "verified_after"
      ],
      "path": "/public/auth/jobs",
      "summary": "The job search the CSV export pages through: the GET /v1/jobs answer with your session instead of a key, the same parameters and the same metering."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/jobs/<id>\" responds {\"data\":{\"id\":\"<job id>\",\"title\":\"Registered Nurse\",\"company\":\"...\"},\"description\":\"<the row's description text>\"}",
      "group": "account",
      "method": "GET",
      "parameters": [
        "id",
        "include_closed"
      ],
      "path": "/public/auth/jobs/{id}",
      "summary": "One job by id (or slug) as the signed-in account: the session twin of GET /v1/jobs/{id}, so include_closed=true and quality=all work the same way."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/export-estimate?country=DE\" responds {\"estimated_rows\":1234,\"export_cap\":5000,\"would_use\":1234,\"remaining_this_month\":9000,\"remaining_unlimited\":false,\"note\":\"asking costs no record quota\"}",
      "group": "account",
      "method": "GET",
      "parameters": [
        "country",
        "category",
        "q",
        "title",
        "require_fields",
        "has_salary"
      ],
      "path": "/public/auth/export-estimate",
      "summary": "What an export of these filters would cost, before you run it: the session twin of GET /v1/me/export-estimate. Unmetered."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -X POST -b cookies.txt -H \"content-type: application/json\" -d '{\"country\":\"DE\",\"family\":\"Engineering\"}' \"https://api.jobopportunitiesapi.org/public/auth/export-packs\" responds 201 {\"id\":\"<id>\",\"status\":\"queued\",\"beta\":true}",
      "group": "account",
      "method": "POST",
      "parameters": [],
      "path": "/public/auth/export-packs",
      "summary": "Queue a whole-country export pack as the signed-in account (the session twin of POST /v1/export-packs, behind the same bulk_export plan gate). One pack at a time per account; the file is kept 7 days."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/export-packs\" responds {\"data\":[{\"id\":\"<id>\",\"country\":\"DE\",\"family\":\"Engineering\",\"status\":\"completed\",\"rows_written\":1234,\"file_bytes\":123456,\"created_at\":\"2026-10-27T09:00:00Z\",\"completed_at\":\"2026-10-27T09:10:00Z\",\"expires_at\":\"2026-11-03T09:10:00Z\",\"download_url\":\"https://api.jobopportunitiesapi.org/public/export-packs/<id>/download?exp=<expiry>&sig=<signature>\"}],\"beta\":true}",
      "group": "account",
      "method": "GET",
      "parameters": [],
      "path": "/public/auth/export-packs",
      "summary": "List your export packs and their state, newest first, at most 50. A completed pack carries its signed download link."
    },
    {
      "auth": "session cookie",
      "example": "curl -s -b cookies.txt \"https://api.jobopportunitiesapi.org/public/auth/export-packs/<id>\" responds {\"data\":{\"id\":\"<id>\",\"country\":\"DE\",\"status\":\"completed\",\"rows_written\":1234,\"download_url\":\"<signed download link>\"},\"beta\":true}",
      "group": "account",
      "method": "GET",
      "parameters": [
        "id"
      ],
      "path": "/public/auth/export-packs/{id}",
      "summary": "One export pack: state, row count and its signed download link."
    },
    {
      "auth": "none",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"plan\":\"signal\",\"email\":\"you@example.com\"}' \"https://api.jobopportunitiesapi.org/public/checkout\"",
      "group": "billing",
      "method": "POST",
      "parameters": [],
      "path": "/public/checkout",
      "summary": "Create a checkout for a plan; returns the merchant's checkout URL."
    },
    {
      "auth": "signed token",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/checkout/status?exp=<token>\"",
      "group": "billing",
      "method": "GET",
      "parameters": [
        "exp"
      ],
      "path": "/public/checkout/status",
      "summary": "Where a checkout ended up, by its token."
    },
    {
      "auth": "signed token",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"token\":\"<from the link>\"}' \"https://api.jobopportunitiesapi.org/public/upgrade/checkout\"",
      "group": "billing",
      "method": "POST",
      "parameters": [],
      "path": "/public/upgrade/checkout",
      "summary": "Turn a signed upgrade link into a checkout URL."
    },
    {
      "auth": "signed token",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"token\":\"<from the link>\"}' \"https://api.jobopportunitiesapi.org/public/offer/checkout\"",
      "group": "billing",
      "method": "POST",
      "parameters": [],
      "path": "/public/offer/checkout",
      "summary": "Checkout from a personalised offer link."
    },
    {
      "auth": "none",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"product\":\"<id>\",\"email\":\"you@example.com\"}' \"https://api.jobopportunitiesapi.org/public/datasets/checkout\"",
      "group": "billing",
      "method": "POST",
      "parameters": [],
      "path": "/public/datasets/checkout",
      "summary": "Buy a dataset product."
    },
    {
      "auth": "none",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"email\":\"you@example.com\"}' \"https://api.jobopportunitiesapi.org/public/datasets/resend\"",
      "group": "billing",
      "method": "POST",
      "parameters": [],
      "path": "/public/datasets/resend",
      "summary": "Re-send a dataset download link to its buyer."
    },
    {
      "auth": "signed token",
      "example": "curl -s -o data.ndjson \"https://api.jobopportunitiesapi.org/public/datasets/<id>/download?sig=<signature>\"",
      "group": "billing",
      "method": "GET",
      "parameters": [
        "id"
      ],
      "path": "/public/datasets/{id}/download",
      "summary": "Download a purchased dataset."
    },
    {
      "auth": "signed token",
      "example": "curl -s -o pack.ndjson \"https://api.jobopportunitiesapi.org/public/export-packs/<id>/download?sig=<signature>\"",
      "group": "billing",
      "method": "GET",
      "parameters": [
        "id"
      ],
      "path": "/public/export-packs/{id}/download",
      "summary": "Download a finished export pack."
    },
    {
      "auth": "signed token",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/invoice/<token>\"",
      "group": "billing",
      "method": "GET",
      "parameters": [
        "token"
      ],
      "path": "/public/invoice/{token}",
      "summary": "One invoice as HTML or PDF."
    },
    {
      "auth": "none",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"vat_number\":\"DE123456789\"}' \"https://api.jobopportunitiesapi.org/public/vat/check\"",
      "group": "billing",
      "method": "POST",
      "parameters": [],
      "path": "/public/vat/check",
      "summary": "Check an EU VAT number and whether it reverse charges."
    },
    {
      "auth": "none",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"email\":\"you@example.com\"}' \"https://api.jobopportunitiesapi.org/public/subscribe\"",
      "group": "feedback",
      "method": "POST",
      "parameters": [],
      "path": "/public/subscribe",
      "summary": "Join the newsletter."
    },
    {
      "auth": "signed token",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/unsubscribe?id=<id>&tok=<token>\"",
      "group": "feedback",
      "method": "GET",
      "parameters": [
        "id",
        "tok"
      ],
      "path": "/public/unsubscribe",
      "summary": "Confirm an unsubscribe from a mailed link."
    },
    {
      "auth": "signed token",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"id\":\"<id>\",\"tok\":\"<token>\"}' \"https://api.jobopportunitiesapi.org/public/unsubscribe\"",
      "group": "feedback",
      "method": "POST",
      "parameters": [],
      "path": "/public/unsubscribe",
      "summary": "Unsubscribe an address after the mailed confirmation."
    },
    {
      "auth": "signed token",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/lifecycle-unsubscribe?id=<id>&tok=<token>&kind=weekly\"",
      "group": "feedback",
      "method": "GET",
      "parameters": [
        "id",
        "tok",
        "kind"
      ],
      "path": "/public/lifecycle-unsubscribe",
      "summary": "Unsubscribe from one product email, from the link in it."
    },
    {
      "auth": "signed token",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"id\":\"<id>\",\"tok\":\"<token>\",\"kind\":\"weekly\"}' \"https://api.jobopportunitiesapi.org/public/lifecycle-unsubscribe\"",
      "group": "feedback",
      "method": "POST",
      "parameters": [],
      "path": "/public/lifecycle-unsubscribe",
      "summary": "The POST form of the same link."
    },
    {
      "auth": "signed token",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/confirm?e=<address>&t=<token>\"",
      "group": "feedback",
      "method": "GET",
      "parameters": [
        "e",
        "t"
      ],
      "path": "/public/confirm",
      "summary": "Confirm an email address change from a mailed link."
    },
    {
      "auth": "signed token",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/welcome-intent?id=<id>&tok=<token>\"",
      "group": "feedback",
      "method": "GET",
      "parameters": [
        "id",
        "tok"
      ],
      "path": "/public/welcome-intent",
      "summary": "The welcome mail's question form."
    },
    {
      "auth": "signed token",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"id\":\"<id>\",\"tok\":\"<token>\",\"intent\":\"integrate\"}' \"https://api.jobopportunitiesapi.org/public/welcome-intent\"",
      "group": "feedback",
      "method": "POST",
      "parameters": [],
      "path": "/public/welcome-intent",
      "summary": "Save the welcome mail's answer."
    },
    {
      "auth": "signed token",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"id\":\"<id>\",\"tok\":\"<token>\",\"note\":\"...\"}' \"https://api.jobopportunitiesapi.org/public/welcome-intent-note\"",
      "group": "feedback",
      "method": "POST",
      "parameters": [],
      "path": "/public/welcome-intent-note",
      "summary": "Save the free-text note beside that answer."
    },
    {
      "auth": "signed token",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/month-rating?id=<id>&tok=<token>\"",
      "group": "feedback",
      "method": "GET",
      "parameters": [
        "id",
        "tok"
      ],
      "path": "/public/month-rating",
      "summary": "The one-month rating form."
    },
    {
      "auth": "signed token",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"id\":\"<id>\",\"tok\":\"<token>\",\"rating\":5}' \"https://api.jobopportunitiesapi.org/public/month-rating\"",
      "group": "feedback",
      "method": "POST",
      "parameters": [],
      "path": "/public/month-rating",
      "summary": "Save a rating."
    },
    {
      "auth": "signed token",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"id\":\"<id>\",\"tok\":\"<token>\",\"note\":\"...\"}' \"https://api.jobopportunitiesapi.org/public/month-rating-note\"",
      "group": "feedback",
      "method": "POST",
      "parameters": [],
      "path": "/public/month-rating-note",
      "summary": "Save the note beside a rating."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/roadmap\"",
      "group": "feedback",
      "method": "GET",
      "parameters": [],
      "path": "/public/roadmap",
      "summary": "The public product roadmap."
    },
    {
      "auth": "none",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"title\":\"...\",\"why\":\"...\"}' \"https://api.jobopportunitiesapi.org/public/roadmap/proposals\"",
      "group": "feedback",
      "method": "POST",
      "parameters": [],
      "path": "/public/roadmap/proposals",
      "summary": "Propose a feature."
    },
    {
      "auth": "none",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"email\":\"you@example.com\",\"message\":\"...\"}' \"https://api.jobopportunitiesapi.org/public/contact\"",
      "group": "feedback",
      "method": "POST",
      "parameters": [],
      "path": "/public/contact",
      "summary": "Contact form."
    },
    {
      "auth": "none",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"url\":\"https://example.com/careers\"}' \"https://api.jobopportunitiesapi.org/public/submissions\"",
      "group": "feedback",
      "method": "POST",
      "parameters": [],
      "path": "/public/submissions",
      "summary": "Submit a job board or a careers page for us to read."
    },
    {
      "auth": "none",
      "example": "curl -s -X POST \"https://api.jobopportunitiesapi.org/public/donate\"",
      "group": "feedback",
      "method": "POST",
      "parameters": [],
      "path": "/public/donate",
      "summary": "Donation endpoint (currently returns where to send it)."
    },
    {
      "auth": "none",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"email\":\"you@example.com\",\"kind\":\"employer_removal\"}' \"https://api.jobopportunitiesapi.org/public/optout/request\"",
      "group": "feedback",
      "method": "POST",
      "parameters": [],
      "path": "/public/optout/request",
      "summary": "Ask for an employer removal or a data opt-out."
    },
    {
      "auth": "signed token",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"id\":\"<id>\",\"tok\":\"<token>\"}' \"https://api.jobopportunitiesapi.org/public/optout/verify\"",
      "group": "feedback",
      "method": "POST",
      "parameters": [],
      "path": "/public/optout/verify",
      "summary": "Confirm an opt-out from the mailed link."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/ai-prompt\"",
      "group": "docs",
      "method": "GET",
      "parameters": [],
      "path": "/public/ai-prompt",
      "summary": "The integration brief as plain text, on the API host."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/openapi.yaml\"",
      "group": "docs",
      "method": "GET",
      "parameters": [],
      "path": "/public/openapi.yaml",
      "summary": "The OpenAPI contract, keyless."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/openapi.json\"",
      "group": "docs",
      "method": "GET",
      "parameters": [],
      "path": "/public/openapi.json",
      "summary": "The OpenAPI contract as JSON, keyless."
    },
    {
      "auth": "none",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/help\"",
      "group": "docs",
      "method": "GET",
      "parameters": [],
      "path": "/public/help",
      "summary": "This document, keyless. Cache it: it is versioned and changes are additive within a version."
    },
    {
      "auth": "none",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}' \"https://api.jobopportunitiesapi.org/mcp\"",
      "group": "tools",
      "method": "GET",
      "parameters": [],
      "path": "/mcp",
      "summary": "The MCP server (JSON-RPC over POST). GET answers 405; the tool list comes from a POST tools/list."
    },
    {
      "auth": "tool dependent",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"search_jobs\",\"arguments\":{\"q\":\"nurse\",\"country\":\"DE\"}}}' \"https://api.jobopportunitiesapi.org/mcp\"",
      "group": "tools",
      "method": "POST",
      "parameters": [],
      "path": "/mcp",
      "summary": "Call an MCP tool: search_jobs, get_job, company_hiring, market_signals, coverage, changes_since, job_status, sponsor_lookup."
    },
    {
      "auth": "none",
      "example": "curl -s -L \"https://api.jobopportunitiesapi.org/o/<code>\"",
      "group": "tools",
      "method": "GET",
      "parameters": [
        "code"
      ],
      "path": "/o/{code}",
      "summary": "Short link to a personalised offer."
    },
    {
      "auth": "none",
      "example": "curl -s -L \"https://api.jobopportunitiesapi.org/offer/<token>\"",
      "group": "tools",
      "method": "GET",
      "parameters": [
        "token"
      ],
      "path": "/offer/{token}",
      "summary": "A personalised offer page from its signed token."
    },
    {
      "auth": "signature",
      "example": "curl -s \"https://api.jobopportunitiesapi.org/public/webhooks/viva\"",
      "group": "webhooks",
      "method": "GET",
      "parameters": [],
      "path": "/public/webhooks/viva",
      "summary": "Viva wallet webhook (inbound, signature checked)."
    },
    {
      "auth": "signature",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d @event.json \"https://api.jobopportunitiesapi.org/public/webhooks/viva\"",
      "group": "webhooks",
      "method": "POST",
      "parameters": [],
      "path": "/public/webhooks/viva",
      "summary": "Viva wallet payment events."
    },
    {
      "auth": "signature",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d @event.json \"https://api.jobopportunitiesapi.org/public/webhooks/creem\"",
      "group": "webhooks",
      "method": "POST",
      "parameters": [],
      "path": "/public/webhooks/creem",
      "summary": "Creem merchant of record webhooks."
    },
    {
      "auth": "signature",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d @event.json \"https://api.jobopportunitiesapi.org/webhooks/revolut\"",
      "group": "webhooks",
      "method": "POST",
      "parameters": [],
      "path": "/webhooks/revolut",
      "summary": "Revolut payment webhooks."
    },
    {
      "auth": "none",
      "example": "curl -s -X POST -H \"content-type: application/json\" -d '{\"order_ref\":\"<uuid>\",\"claim_token\":\"<from the checkout>\"}' \"https://api.jobopportunitiesapi.org/public/checkout/claim\"",
      "group": "billing",
      "method": "POST",
      "parameters": [],
      "path": "/public/checkout/claim",
      "summary": "Show the first key's secret once, after payment, with the order ref and the claim token from the checkout. A reload answers 409 already_claimed; the secret is never shown twice."
    }
  ],
  "error_codes": [
    {
      "code": "unknown_parameter",
      "fix": "Check the spelling against the parameters table; the error carries a did-you-mean.",
      "retry": false,
      "status": 400,
      "when": "The request names a parameter the endpoint does not read."
    },
    {
      "code": "unsupported_parameter",
      "fix": "Remove it.",
      "retry": false,
      "status": 400,
      "when": "The parameter exists on another endpoint but not this one (limit on /v1/export, for example). GET /v1/jobs answers it to include_closed (any value), which only GET /v1/jobs/{id} reads: closed roles in a list come from GET /v1/jobs/closed or status=any. Since 11 Nov 2026 (it was accepted and ignored before). Nothing is charged."
    },
    {
      "code": "paid_feature",
      "fix": "Move the call to /v1.",
      "retry": false,
      "status": 403,
      "when": "A /v1 only parameter was sent to a /public route (status, quality, include_poster_type)."
    },
    {
      "code": "not_found",
      "fix": "On a company slug, follow the 301 first.",
      "retry": false,
      "status": 404,
      "when": "No such id or slug."
    },
    {
      "code": "query_syntax",
      "fix": "The message names the problem and its character position.",
      "retry": false,
      "status": 422,
      "when": "The query grammar cannot honour the value: an unmatched parenthesis, an empty group, an operator without an operand. Since 25 Oct 2026."
    },
    {
      "code": "query_too_complex",
      "fix": "Split the query or shorten it. The message names the character position.",
      "retry": false,
      "status": 422,
      "when": "A boolean expression over a grammar limit: more than 32 terms or a prefix shorter than 3 characters (plain values have no such limit), or parentheses nested more than 8 deep in any value (plain values too since 11 Nov 2026). Since 10 Nov 2026."
    },
    {
      "code": "bad_limit",
      "fix": "Send a number in range.",
      "retry": false,
      "status": 422,
      "when": "limit is not a whole number inside the endpoint's range."
    },
    {
      "code": "limit_too_large",
      "fix": "Ask for 50 or fewer rows.",
      "retry": false,
      "status": 422,
      "when": "limit above 50 with include_description=true."
    },
    {
      "code": "filter_too_long",
      "fix": "Shorten it. Over-long filters are refused, never ignored.",
      "retry": false,
      "status": 422,
      "when": "A text filter (q, title, title_exclude, description_contains, company_name_contains) of 500 bytes or more. The limit was 200 bytes until 10 Nov 2026."
    },
    {
      "code": "description_contains_live_only",
      "fix": "Search live postings with description_contains; use title or q for closed postings.",
      "retry": false,
      "status": 422,
      "when": "description_contains with status=closed or any, or on /v1/jobs/closed or /v1/jobs/expired."
    },
    {
      "code": "query_has_no_terms",
      "fix": "Give it at least one word or number.",
      "retry": false,
      "status": 422,
      "when": "A text filter that is only operators and punctuation."
    },
    {
      "code": "bad_boolean",
      "fix": "Send true or false.",
      "retry": false,
      "status": 422,
      "when": "A flag is not true or false."
    },
    {
      "code": "bad_has_salary",
      "fix": "Use one of those four.",
      "retry": false,
      "status": 422,
      "when": "has_salary is not true, structured, any or false."
    },
    {
      "code": "bad_country",
      "fix": "The message suggests the code you meant (UK to GB, EL to GR).",
      "retry": false,
      "status": 422,
      "when": "country or exclude_country holds a value that is not an ISO code."
    },
    {
      "code": "bad_category",
      "fix": "Read the vocabulary from /v1/meta/facets.",
      "retry": false,
      "status": 422,
      "when": "An unknown category or family."
    },
    {
      "code": "bad_provider",
      "fix": "Read the vocabulary from /v1/meta/providers.",
      "retry": false,
      "status": 422,
      "when": "An unknown provider slug."
    },
    {
      "code": "too_many_values",
      "fix": "Split the request. Values are never dropped silently.",
      "retry": false,
      "status": 422,
      "when": "A comma list longer than the parameter's maximum."
    },
    {
      "code": "offset_not_supported",
      "fix": "Page with cursor.",
      "retry": false,
      "status": 422,
      "when": "A non-zero offset on a cursor paged endpoint."
    },
    {
      "code": "bad_cursor",
      "fix": "Pass next_cursor back verbatim (URL encoded), or start from the first page.",
      "retry": false,
      "status": 422,
      "when": "The cursor is not one we issued or was changed on the way. Since 11 Nov 2026 this includes a /v1/companies cursor whose rank is out of range or that carries a NUL byte or invalid UTF-8 (those answered 500 query_failed before)."
    },
    {
      "code": "sort_unavailable",
      "fix": "Drop the parameter.",
      "retry": false,
      "status": 422,
      "when": "sort was sent while ranked search is off on this deployment."
    },
    {
      "code": "bad_parameter_value",
      "fix": "Re-encode the request, or correct the kind of value the message names.",
      "retry": false,
      "status": 422,
      "when": "A NUL byte or invalid UTF-8 in any value. Since 11 Nov 2026 also any value the database cannot use (a date, number, id or cursor it cannot convert), which used to answer 500 query_failed; the message names the kind of value, never the database text. Time filters are checked first and answer their own code (a year 0000 or a UTC offset of 16 hours or more in posted_after is 422 bad_posted_after, for example). Never retryable unchanged."
    },
    {
      "code": "rate_limited",
      "fix": "Retry after the Retry-After header.",
      "retry": true,
      "status": 429,
      "when": "Too many requests for this plan."
    },
    {
      "code": "timeout",
      "fix": "Retry in a few seconds, and narrow the filter (a country, fewer require_fields).",
      "retry": true,
      "status": 503,
      "when": "The query ran past the statement timeout."
    },
    {
      "code": "query_failed",
      "fix": "Retry once at most; if it repeats, report it with the X-Request-Id of the response.",
      "retry": false,
      "status": 500,
      "when": "An unexpected database error: not the statement timeout (503 timeout) and not a value the database cannot use (422 bad_parameter_value). It points at a defect on our side, so retrying the same request rarely helps."
    },
    {
      "code": "missing_employers",
      "fix": "Send 1 to 100 employers, each with a name: {\"employers\": [{\"name\": \"Acme Ltd\", \"country\": \"GB\"}]}.",
      "retry": false,
      "status": 422,
      "when": "POST /v1/sponsors/lookup without employers. Nothing is charged."
    },
    {
      "code": "too_many_employers",
      "fix": "Send 1 to 100 employers, each with a name: {\"employers\": [{\"name\": \"Acme Ltd\", \"country\": \"GB\"}]}.",
      "retry": false,
      "status": 422,
      "when": "POST /v1/sponsors/lookup with more than 100 employers. Nothing is charged."
    },
    {
      "code": "missing_name",
      "fix": "Send 1 to 100 employers, each with a name: {\"employers\": [{\"name\": \"Acme Ltd\", \"country\": \"GB\"}]}.",
      "retry": false,
      "status": 422,
      "when": "A sponsor lookup employer without a name: on GET, or on a POST in which no employer can be looked up. On a POST with other employers, that employer is answered with status invalid instead and the call answers 200. Nothing is charged."
    },
    {
      "code": "conflicting_parameters",
      "fix": "Send one of the two.",
      "retry": false,
      "status": 400,
      "when": "A Fantastic.jobs alias and its JOA name are both set with different values (title_advanced and title, for example)."
    },
    {
      "code": "busy",
      "fix": "Retry after the Retry-After seconds. Nothing was charged.",
      "retry": true,
      "status": 503,
      "when": "Too many boolean text searches are running at once (a request with a boolean q, title, title_exclude, description_contains or company_name_contains). Since 11 Nov 2026."
    },
    {
      "code": "unauthorized",
      "fix": "Send Authorization: Bearer <key>.",
      "retry": false,
      "status": 401,
      "when": "No Authorization header, an empty bearer token, or a key in the wrong form on a route that needs a key."
    },
    {
      "code": "invalid_key",
      "fix": "Check the key in your account, or create a new one.",
      "retry": false,
      "status": 401,
      "when": "The key is unknown, revoked or expired."
    },
    {
      "code": "demo_token_not_valid_for_api",
      "fix": "Use your own key; the demo token only works on the website.",
      "retry": false,
      "status": 401,
      "when": "The website's demo token was sent to the API."
    },
    {
      "code": "key_required",
      "fix": "Use a key on the /v1 endpoint. A free key needs no card.",
      "retry": false,
      "status": 401,
      "when": "No key where one is needed: /public/jobs, /public/jobs/{id}, /public/companies or /public/companies/{slug} without a key (401), the export packs without a key (401), or include=embedding on a /public route (403)."
    },
    {
      "code": "listings_need_v1",
      "fix": "Call the same query on /v1/jobs, /v1/jobs/{id}, /v1/companies or /v1/companies/{slug} with your key.",
      "retry": false,
      "status": 403,
      "when": "An Authorization header was sent to /public/jobs, /public/jobs/{id}, /public/companies or /public/companies/{slug}. Those routes serve the website's own pages and no longer serve listing rows to anyone else, with a key or without. Status 403 when the header names a usable key (authenticated, not served here); status 401 when it does not (an unknown, revoked or demo key, or an empty bearer). Same code and message either way. With no Authorization header at all these routes answer 401 key_required. Since 11 Nov 2026 (a usable key got 401 before)."
    },
    {
      "code": "record_quota_exhausted",
      "fix": "Wait for resets_at, or open upgrade_url or an upgrade.options[].checkout_url. Do not retry before resets_at.",
      "retry": false,
      "status": 402,
      "when": "The month's record allowance is used up. The body carries limit, used, window and resets_at. When a plan can lift the limit it also carries upgrade_plan and upgrade_url (the first option) and an upgrade object: upgrade.demand (window_days, records_delivered, refused_calls, records_refused and records: what the account asked for in the last 30 days, refused calls included) and upgrade.options (the smallest plan that covers that demand first, then the next plan up, each with plan, name, records_per_month, price_cents, currency, interval, price_text, vat, covers_demand, one_click and checkout_url, and while a published price offer runs for that plan and the link starts a new checkout, offer: name, percent, price_cents, price_text, regular_price_cents, regular_price_text, recurring, code, ends_at). The prices are the ones on https://jobopportunitiesapi.org/pricing, excl. VAT."
    },
    {
      "code": "plan_upgrade_required",
      "fix": "Upgrade, or read what the plan covers at https://jobopportunitiesapi.org/api.",
      "retry": false,
      "status": 403,
      "when": "The endpoint is not on this plan (the change feed /v1/changes and bulk export are Growth and above). The X-JOA-Required-Feature header names the feature."
    },
    {
      "code": "key_endpoint_not_configured",
      "fix": "Use a key allowed on this endpoint, or change the key's endpoints in your account.",
      "retry": false,
      "status": 403,
      "when": "The key is restricted to a list of endpoints and this is not one of them. The message names the endpoint code; /v1/me lists the key's endpoints."
    },
    {
      "code": "direct_origin_blocked",
      "fix": "Call https://api.jobopportunitiesapi.org.",
      "retry": false,
      "status": 403,
      "when": "The request reached the origin server directly instead of the public endpoint."
    },
    {
      "code": "method_not_allowed",
      "fix": "Use one of the allowed methods.",
      "retry": false,
      "status": 405,
      "when": "The HTTP method is not supported on this path. The Allow header and the message name the methods that are."
    },
    {
      "code": "closed",
      "fix": "Send include_closed=true to read the closed role.",
      "retry": false,
      "status": 410,
      "when": "The job has closed. /v1/jobs/{id} without include_closed."
    },
    {
      "code": "gone",
      "fix": "Drop it from your copy; /v1/jobs/withdrawn lists these.",
      "retry": false,
      "status": 410,
      "when": "The employer has withdrawn the listing."
    },
    {
      "code": "body_too_large",
      "fix": "Send a smaller body.",
      "retry": false,
      "status": 413,
      "when": "The request body is too large to read."
    },
    {
      "code": "empty_value",
      "fix": "Remove the parameter entirely, or give it a value.",
      "retry": false,
      "status": 422,
      "when": "A parameter is present with no value. An empty value is never read as no filter."
    },
    {
      "code": "missing_since",
      "fix": "Send since=<RFC 3339 time>, for example since=2026-07-01T00:00:00Z.",
      "retry": false,
      "status": 400,
      "when": "/v1/jobs/expired or /v1/jobs/withdrawn without since."
    },
    {
      "code": "bad_since",
      "fix": "Send RFC 3339, YYYY-MM-DD, a relative value (now-1d, yesterday) or the next_since token verbatim.",
      "retry": false,
      "status": 422,
      "when": "since is not a time or a next_since token we accept (status 400 on /v1/jobs/expired and /v1/jobs/withdrawn, 422 elsewhere)."
    },
    {
      "code": "bad_posted_after",
      "fix": "Send RFC 3339, YYYY-MM-DD, or a relative value: now, now-15m, now-2h, now-1d, today, yesterday (UTC).",
      "retry": false,
      "status": 422,
      "when": "posted_after is not a time we accept."
    },
    {
      "code": "bad_posted_before",
      "fix": "Send RFC 3339, YYYY-MM-DD, or a relative value: now, now-15m, now-2h, now-1d, today, yesterday (UTC).",
      "retry": false,
      "status": 422,
      "when": "posted_before is not a time we accept."
    },
    {
      "code": "bad_listed_after",
      "fix": "Send RFC 3339, YYYY-MM-DD, or a relative value: now, now-15m, now-2h, now-1d, today, yesterday (UTC).",
      "retry": false,
      "status": 422,
      "when": "listed_after is not a time we accept."
    },
    {
      "code": "bad_listed_before",
      "fix": "Send RFC 3339, YYYY-MM-DD, or a relative value: now, now-15m, now-2h, now-1d, today, yesterday (UTC).",
      "retry": false,
      "status": 422,
      "when": "listed_before is not a time we accept."
    },
    {
      "code": "bad_verified_after",
      "fix": "Send RFC 3339, YYYY-MM-DD, or a relative value: now, now-15m, now-2h, now-1d, today, yesterday (UTC).",
      "retry": false,
      "status": 422,
      "when": "verified_after is not a time we accept."
    },
    {
      "code": "bad_verified_before",
      "fix": "Send RFC 3339, YYYY-MM-DD, or a relative value: now, now-15m, now-2h, now-1d, today, yesterday (UTC).",
      "retry": false,
      "status": 422,
      "when": "verified_before is not a time we accept."
    },
    {
      "code": "bad_closed_after",
      "fix": "Send RFC 3339, YYYY-MM-DD, or a relative value (now-1d, yesterday).",
      "retry": false,
      "status": 422,
      "when": "closed_after on /v1/jobs/closed is not a time we accept."
    },
    {
      "code": "bad_closed_before",
      "fix": "Send RFC 3339, YYYY-MM-DD, or a relative value (now-1d, yesterday).",
      "retry": false,
      "status": 422,
      "when": "closed_before on /v1/jobs/closed is not a time we accept."
    },
    {
      "code": "bound_unavailable",
      "fix": "Retry.",
      "retry": true,
      "status": 503,
      "when": "The upper bound of a since poll could not be fixed. Nothing is charged."
    },
    {
      "code": "bad_seniority",
      "fix": "Use Intern, Entry, Mid, Senior, Lead, Manager, Director, Executive or not_stated (any case); the seniority facet of /public/facets is the live list.",
      "retry": false,
      "status": 422,
      "when": "An unknown seniority value."
    },
    {
      "code": "bad_remote",
      "fix": "Use remote, hybrid, on_site or not_stated.",
      "retry": false,
      "status": 422,
      "when": "An unknown remote value."
    },
    {
      "code": "bad_employment_type",
      "fix": "Use Full-time, Part-time, Contract, Internship, Temporary or not_stated (any case).",
      "retry": false,
      "status": 422,
      "when": "An unknown employment_type value."
    },
    {
      "code": "bad_compensation_type",
      "fix": "Use salary, commission, tips or equity.",
      "retry": false,
      "status": 422,
      "when": "An unknown compensation_type or exclude_compensation_type value."
    },
    {
      "code": "bad_exclude_country",
      "fix": "The message suggests the code you meant.",
      "retry": false,
      "status": 422,
      "when": "exclude_country holds a value that is not an ISO code."
    },
    {
      "code": "bad_country_confidence",
      "fix": "Send high or low.",
      "retry": false,
      "status": 422,
      "when": "country_confidence is not high or low."
    },
    {
      "code": "bad_country_match",
      "fix": "Send primary (the default) or any.",
      "retry": false,
      "status": 422,
      "when": "country_match is not primary or any."
    },
    {
      "code": "bad_sponsor_register",
      "fix": "Send any, or a comma list of GB, NL, US, CA, IE, DK.",
      "retry": false,
      "status": 422,
      "when": "sponsor_register is not any or a list of the register countries."
    },
    {
      "code": "bad_visa_text",
      "fix": "Send visa_text=stated_open or visa_text=stated_closed (one value).",
      "retry": false,
      "status": 422,
      "when": "visa_text is not exactly one of stated_open or stated_closed."
    },
    {
      "code": "bad_region",
      "fix": "Use an ISO 3166-2 code (GB-DEV, US-OH, CA-ON, AU-WA) or the English name (Devon).",
      "retry": false,
      "status": 422,
      "when": "An unknown region."
    },
    {
      "code": "bad_state",
      "fix": "Use two letter US state codes, for example state=OH,TX.",
      "retry": false,
      "status": 422,
      "when": "An unknown state."
    },
    {
      "code": "bad_source_type",
      "fix": "Use ats, career_site, public_agency, aggregator or agency.",
      "retry": false,
      "status": 422,
      "when": "An unknown source_type or exclude_source_type value."
    },
    {
      "code": "bad_require_fields",
      "fix": "Use the fields the message lists; the field facet of /v1/meta/facets counts them.",
      "retry": false,
      "status": 422,
      "when": "require_fields names a field it cannot require."
    },
    {
      "code": "field_never_published",
      "fix": "Filter the value with its own parameter instead (seniority=).",
      "retry": false,
      "status": 422,
      "when": "require_fields names a field we always infer and never publish as stated (seniority, for example)."
    },
    {
      "code": "bad_min_salary",
      "fix": "Send a number, for example 60000.",
      "retry": false,
      "status": 422,
      "when": "min_salary is not a non-negative number."
    },
    {
      "code": "bad_max_salary",
      "fix": "Send a number, for example 120000.",
      "retry": false,
      "status": 422,
      "when": "max_salary is not a non-negative number."
    },
    {
      "code": "bad_status",
      "fix": "Send live, closed or any.",
      "retry": false,
      "status": 422,
      "when": "status is not live, closed or any."
    },
    {
      "code": "bad_include_poster_type",
      "fix": "Send staffing, jobboard or all.",
      "retry": false,
      "status": 422,
      "when": "include_poster_type is not staffing, jobboard or all."
    },
    {
      "code": "bad_include",
      "fix": "Send include=embedding, or leave it out.",
      "retry": false,
      "status": 422,
      "when": "include holds a value other than embedding."
    },
    {
      "code": "bad_engagement",
      "fix": "Use employee, vendor, other or unknown.",
      "retry": false,
      "status": 422,
      "when": "An unknown engagement value."
    },
    {
      "code": "bad_contract_category",
      "fix": "Use permanent, fixed_term, project_based, seasonal, apprenticeship, internship, other or unknown.",
      "retry": false,
      "status": 422,
      "when": "An unknown contract_category value."
    },
    {
      "code": "bad_agency",
      "fix": "Use direct, agency, umbrella or unknown.",
      "retry": false,
      "status": 422,
      "when": "An unknown agency value."
    },
    {
      "code": "bad_working_schedule",
      "fix": "Use full_time, part_time, flexible or unknown.",
      "retry": false,
      "status": 422,
      "when": "An unknown working_schedule value."
    },
    {
      "code": "bad_collapse",
      "fix": "Send collapse=company, or leave it out.",
      "retry": false,
      "status": 422,
      "when": "collapse holds a value other than company."
    },
    {
      "code": "bad_max_per_company",
      "fix": "Send a whole number from 1 to the limit the message states.",
      "retry": false,
      "status": 422,
      "when": "max_per_company is not a whole number in range."
    },
    {
      "code": "flood_params_conflict",
      "fix": "Send one of the two.",
      "retry": false,
      "status": 422,
      "when": "collapse=company with a max_per_company other than 1."
    },
    {
      "code": "flood_control_not_supported",
      "fix": "Use the default order for those.",
      "retry": false,
      "status": 422,
      "when": "collapse or max_per_company with sort=relevance."
    },
    {
      "code": "include_total_not_supported",
      "fix": "Drop include_total, or use the default order.",
      "retry": false,
      "status": 422,
      "when": "include_total with sort=relevance."
    },
    {
      "code": "relevance_not_in_plan",
      "fix": "Use the default order, or upgrade.",
      "retry": false,
      "status": 422,
      "when": "sort=relevance on a plan without a relevance budget."
    },
    {
      "code": "ranked_budget_exhausted",
      "fix": "Retry after 00:00 UTC, or use the default order.",
      "retry": true,
      "status": 429,
      "when": "The plan's daily sort=relevance budget is spent. The default order is not limited by it."
    },
    {
      "code": "sort_unknown",
      "fix": "Send sort=relevance, or leave it out.",
      "retry": false,
      "status": 422,
      "when": "sort holds a value other than relevance."
    },
    {
      "code": "sort_requires_q",
      "fix": "Add q.",
      "retry": false,
      "status": 422,
      "when": "sort=relevance without q."
    },
    {
      "code": "query_too_long",
      "fix": "Shorten q.",
      "retry": false,
      "status": 422,
      "when": "q of 200 bytes or more with sort=relevance."
    },
    {
      "code": "relevance_requires_key",
      "fix": "Send a key.",
      "retry": false,
      "status": 422,
      "when": "sort=relevance without a key."
    },
    {
      "code": "offset_too_deep",
      "fix": "Page with cursor: it has no depth limit.",
      "retry": false,
      "status": 422,
      "when": "offset on /v1/companies above its cap."
    },
    {
      "code": "bad_offset",
      "fix": "Send a whole number from 0.",
      "retry": false,
      "status": 422,
      "when": "offset on /v1/companies is not a non-negative whole number."
    },
    {
      "code": "bad_after",
      "fix": "Send the id of the last row you received.",
      "retry": false,
      "status": 422,
      "when": "after on /v1/export is not the id of a row."
    },
    {
      "code": "too_many_ids",
      "fix": "Split the list into several calls.",
      "retry": false,
      "status": 422,
      "when": "POST /v1/jobs/status with more than 1000 ids. Nothing is charged."
    },
    {
      "code": "missing_ids",
      "fix": "Send 1 to 1000 job ids: {\"ids\": [\"<job id>\"]}.",
      "retry": false,
      "status": 422,
      "when": "POST /v1/jobs/status without ids. Nothing is charged."
    },
    {
      "code": "bad_id",
      "fix": "Send the id as you received it.",
      "retry": false,
      "status": 422,
      "when": "An id in the path or the body is not a valid id (status 400 on some account routes)."
    },
    {
      "code": "bad_body",
      "fix": "Send the object the message shows.",
      "retry": false,
      "status": 422,
      "when": "The body of POST /v1/jobs/status, POST /v1/jobs/similar or POST /v1/sponsors/lookup is not the one JSON object the endpoint takes. Nothing is charged."
    },
    {
      "code": "bad_parameter",
      "fix": "Send it once.",
      "retry": false,
      "status": 422,
      "when": "A sponsor lookup parameter was sent more than once. Nothing is charged."
    },
    {
      "code": "bad_name",
      "fix": "Shorten the name; the message states the limit.",
      "retry": false,
      "status": 422,
      "when": "A sponsor lookup name over the length limit, or a saved search or list name that is empty or too long."
    },
    {
      "code": "bad_place",
      "fix": "Shorten it.",
      "retry": false,
      "status": 422,
      "when": "A sponsor lookup town or region over 100 characters. Nothing is charged."
    },
    {
      "code": "bad_query",
      "fix": "Send exactly one.",
      "retry": false,
      "status": 422,
      "when": "/v1/jobs/similar needs exactly one of job_id, vector or text. Nothing is charged."
    },
    {
      "code": "bad_vector",
      "fix": "Send 1024 finite numbers.",
      "retry": false,
      "status": 422,
      "when": "The vector holds a value that is not a finite number. Nothing is charged."
    },
    {
      "code": "bad_min_score",
      "fix": "Send a cosine similarity from -1 to 1.",
      "retry": false,
      "status": 422,
      "when": "min_score is not a number from -1 to 1. Nothing is charged."
    },
    {
      "code": "parameter_not_supported",
      "fix": "Remove it; the message says why.",
      "retry": false,
      "status": 422,
      "when": "A parameter /v1/jobs/similar does not support. Nothing is charged."
    },
    {
      "code": "job_has_no_vector",
      "fix": "Retry later, or search by vector.",
      "retry": false,
      "status": 422,
      "when": "The job given as job_id has no stored vector yet (the newest postings are still being embedded). Nothing is charged."
    },
    {
      "code": "text_too_long",
      "fix": "Shorten it.",
      "retry": false,
      "status": 422,
      "when": "The text query is longer than the limit the message states. Nothing is charged."
    },
    {
      "code": "text_query_unavailable",
      "fix": "Embed the text yourself as the message describes and send it as vector.",
      "retry": false,
      "status": 501,
      "when": "Text queries on /v1/jobs/similar are not available yet. Nothing is charged."
    },
    {
      "code": "text_search_busy",
      "fix": "Retry in a few seconds, or search by vector or job_id.",
      "retry": true,
      "status": 503,
      "when": "Text search is busy. Nothing is charged."
    },
    {
      "code": "text_search_unavailable",
      "fix": "Retry in a minute, or search by vector or job_id.",
      "retry": true,
      "status": 503,
      "when": "Text search is briefly unavailable. Nothing is charged."
    },
    {
      "code": "semantic_search_unavailable",
      "fix": "Retry in a minute; every other endpoint keeps working.",
      "retry": true,
      "status": 503,
      "when": "Semantic search is briefly unavailable. Nothing is charged."
    },
    {
      "code": "bad_or_expired_link",
      "fix": "Ask for a new link.",
      "retry": false,
      "status": 403,
      "when": "A dataset or export pack download link is invalid or has expired."
    },
    {
      "code": "bad_family",
      "fix": "Read the vocabulary from /v1/meta/facets.",
      "retry": false,
      "status": 422,
      "when": "An export pack names an unknown category."
    },
    {
      "code": "no_account",
      "fix": "Use GET /v1/export instead.",
      "retry": false,
      "status": 422,
      "when": "An export pack was asked for with a key that is not linked to an account."
    },
    {
      "code": "pack_in_progress",
      "fix": "Wait for it; GET /v1/export-packs shows it.",
      "retry": false,
      "status": 409,
      "when": "An export pack is already queued or running for this account."
    },
    {
      "code": "not_configured",
      "fix": "Use GET /v1/export.",
      "retry": true,
      "status": 503,
      "when": "Export packs are not configured on this deployment yet."
    },
    {
      "code": "not_ready_or_expired",
      "fix": "Check GET /v1/export-packs/{id}.",
      "retry": false,
      "status": 404,
      "when": "The export pack is not ready yet, or has expired."
    },
    {
      "code": "file_missing",
      "fix": "Write to support@jobopportunitiesapi.org.",
      "retry": false,
      "status": 404,
      "when": "The files of a dataset or export pack are not available."
    },
    {
      "code": "scan_failed",
      "fix": "Retry after a moment.",
      "retry": true,
      "status": 500,
      "when": "Rows were read but could not be decoded."
    },
    {
      "code": "internal_error",
      "fix": "Retry after a moment; if it repeats, write to support@jobopportunitiesapi.org with the X-Request-Id.",
      "retry": true,
      "status": 500,
      "when": "Something went wrong on our side."
    },
    {
      "code": "unavailable",
      "fix": "Retry after a moment.",
      "retry": true,
      "status": 503,
      "when": "A dependency is briefly unavailable (the key check, the quota check, a feature's store). Status 500 on a few account routes."
    },
    {
      "code": "unhealthy",
      "fix": "Retry after a moment.",
      "retry": true,
      "status": 503,
      "when": "GET /health: the database is unreachable."
    },
    {
      "code": "stats_unavailable",
      "fix": "Retry shortly.",
      "retry": true,
      "status": 503,
      "when": "Listing statistics are briefly unavailable."
    },
    {
      "code": "sitemap_unavailable",
      "fix": "Retry shortly.",
      "retry": true,
      "status": 503,
      "when": "Sitemap boundaries are being rebuilt."
    },
    {
      "code": "sitemap_meta_unavailable",
      "fix": "Retry shortly.",
      "retry": true,
      "status": 503,
      "when": "Sitemap chunk counts are briefly unavailable."
    },
    {
      "code": "spec_unavailable",
      "fix": "Retry in a moment.",
      "retry": true,
      "status": 503,
      "when": "The OpenAPI document is briefly unavailable."
    },
    {
      "code": "spec_unreadable",
      "fix": "Read /v1/openapi.yaml, or retry.",
      "retry": true,
      "status": 500,
      "when": "The OpenAPI document could not be rendered as JSON."
    },
    {
      "code": "prompt_unavailable",
      "fix": "Retry in a moment.",
      "retry": true,
      "status": 503,
      "when": "The integration brief is briefly unavailable."
    },
    {
      "code": "bad_json",
      "fix": "Send the JSON object the route documents.",
      "retry": false,
      "status": 400,
      "when": "The body is not the JSON the route takes."
    },
    {
      "code": "unreadable",
      "fix": "Send it again.",
      "retry": false,
      "status": 400,
      "when": "The request body could not be read."
    },
    {
      "code": "bad_request",
      "fix": "Correct the field the message names.",
      "retry": false,
      "status": 400,
      "when": "A field of an account area request is missing or unknown (status 422 on some routes)."
    },
    {
      "code": "not_signed_in",
      "fix": "Sign in again.",
      "retry": false,
      "status": 401,
      "when": "An account route was called without a valid session."
    },
    {
      "code": "bad_token",
      "fix": "Ask for a new link.",
      "retry": false,
      "status": 400,
      "when": "A signed link or sign-in token is not valid or has expired (status 403 on some routes)."
    },
    {
      "code": "bad_signature",
      "fix": "Sign with the shared secret the provider holds.",
      "retry": false,
      "status": 401,
      "when": "A webhook delivery's signature does not match."
    },
    {
      "code": "invalid_signature",
      "fix": "Sign with the shared secret.",
      "retry": false,
      "status": 401,
      "when": "A partner webhook's signature verification failed."
    },
    {
      "code": "webhook_unconfigured",
      "fix": "Retry later.",
      "retry": true,
      "status": 503,
      "when": "Webhook verification is not configured on this deployment."
    },
    {
      "code": "retry_later",
      "fix": "The provider retries it.",
      "retry": true,
      "status": 503,
      "when": "A webhook event could not be processed now."
    },
    {
      "code": "unrecognised_source",
      "fix": "None: only the provider sends these.",
      "retry": false,
      "status": 403,
      "when": "A payment notification from an address we do not accept."
    },
    {
      "code": "unconfigured",
      "fix": "Retry later.",
      "retry": true,
      "status": 503,
      "when": "The payment provider credentials are not configured on this deployment."
    },
    {
      "code": "not_recorded",
      "fix": "Retry.",
      "retry": true,
      "status": 500,
      "when": "A payment event could not be recorded."
    },
    {
      "code": "human_check_failed",
      "fix": "Reload the page and try again.",
      "retry": false,
      "status": 403,
      "when": "The human check of a website form failed."
    },
    {
      "code": "too_many",
      "fix": "Try again tomorrow.",
      "retry": true,
      "status": 429,
      "when": "Too many submissions of a website form from this address today."
    },
    {
      "code": "invalid_email",
      "fix": "Give an address we can reach.",
      "retry": false,
      "status": 422,
      "when": "An email address we cannot use."
    },
    {
      "code": "short_message",
      "fix": "Write a little more.",
      "retry": false,
      "status": 422,
      "when": "A contact or support message under one sentence."
    },
    {
      "code": "long_message",
      "fix": "Shorten it.",
      "retry": false,
      "status": 422,
      "when": "A contact or support message over 8000 characters."
    },
    {
      "code": "could_not_send",
      "fix": "Retry, or write to support@jobopportunitiesapi.org.",
      "retry": true,
      "status": 503,
      "when": "A support message did not send."
    },
    {
      "code": "invalid_company",
      "fix": "Give the company name.",
      "retry": false,
      "status": 422,
      "when": "A job submission without a company name of 2 to 160 characters."
    },
    {
      "code": "invalid_title",
      "fix": "Use the length the message states.",
      "retry": false,
      "status": 422,
      "when": "A job submission or feature request title of the wrong length."
    },
    {
      "code": "invalid_url",
      "fix": "Give the full URL.",
      "retry": false,
      "status": 422,
      "when": "A job submission apply link that is not a full http(s) URL."
    },
    {
      "code": "short_description",
      "fix": "Describe the role in more detail.",
      "retry": false,
      "status": 422,
      "when": "A job submission description under 40 characters."
    },
    {
      "code": "invalid_category",
      "fix": "Pick a listed category.",
      "retry": false,
      "status": 422,
      "when": "A feature request without one of the listed categories."
    },
    {
      "code": "invalid_description",
      "fix": "Describe the feature in 20 to 2000 characters.",
      "retry": false,
      "status": 422,
      "when": "A feature request description outside 20 to 2000 characters."
    },
    {
      "code": "no_topics",
      "fix": "Pick at least one topic.",
      "retry": false,
      "status": 422,
      "when": "A mail subscription with no topic selected."
    },
    {
      "code": "bad_heard_from",
      "fix": "Pick a listed answer.",
      "retry": false,
      "status": 422,
      "when": "An answer that is not one of the listed ones."
    },
    {
      "code": "bad_tool",
      "fix": "Give the tool's name.",
      "retry": false,
      "status": 400,
      "when": "A feedback note without a tool name of 2 to 80 characters."
    },
    {
      "code": "bad_kind",
      "fix": "Use the kinds the message lists.",
      "retry": false,
      "status": 422,
      "when": "An export log or feedback kind we do not know."
    },
    {
      "code": "bad_text",
      "fix": "Write the text, or delete the note.",
      "retry": false,
      "status": 422,
      "when": "An empty note or feedback text."
    },
    {
      "code": "bad_filters",
      "fix": "Send the query as an object.",
      "retry": false,
      "status": 422,
      "when": "An export log entry whose filters are not an object."
    },
    {
      "code": "bad_rows",
      "fix": "Record 0 rows.",
      "retry": false,
      "status": 422,
      "when": "An export log entry for a blocked run with a row count other than 0."
    },
    {
      "code": "bad_key_id",
      "fix": "Send the key_id /v1/me gives.",
      "retry": false,
      "status": 422,
      "when": "key_id is not a key id."
    },
    {
      "code": "bad_job_id",
      "fix": "Send the job's id.",
      "retry": false,
      "status": 422,
      "when": "A note's job_id is not a job id."
    },
    {
      "code": "bad_job_ids",
      "fix": "Send job ids.",
      "retry": false,
      "status": 422,
      "when": "A saved list entry is not a job id."
    },
    {
      "code": "bad_list_id",
      "fix": "Send the list's id.",
      "retry": false,
      "status": 422,
      "when": "A note's list_id is not a list id."
    },
    {
      "code": "bad_listing_id",
      "fix": "Send the job's id.",
      "retry": false,
      "status": 422,
      "when": "A watched listing_id is not a job id."
    },
    {
      "code": "bad_channel",
      "fix": "Send email or webhook.",
      "retry": false,
      "status": 422,
      "when": "An alert channel_type other than email or webhook."
    },
    {
      "code": "bad_webhook_url",
      "fix": "Give a public https URL.",
      "retry": false,
      "status": 422,
      "when": "An alert webhook URL we cannot deliver to."
    },
    {
      "code": "bad_frequency",
      "fix": "Send off, daily or weekly.",
      "retry": false,
      "status": 422,
      "when": "An alert_frequency other than off, daily or weekly."
    },
    {
      "code": "bad_threshold",
      "fix": "Send a number from 1 to 100.",
      "retry": false,
      "status": 422,
      "when": "A usage warning threshold_pct outside 1 to 100."
    },
    {
      "code": "bad_days",
      "fix": "Use the range the message states.",
      "retry": false,
      "status": 422,
      "when": "A usage window outside its range."
    },
    {
      "code": "bad_metric",
      "fix": "Send metric=requests.",
      "retry": false,
      "status": 422,
      "when": "A usage metric other than requests."
    },
    {
      "code": "duplicate_alert",
      "fix": "Edit the existing one.",
      "retry": false,
      "status": 409,
      "when": "A usage warning that already exists."
    },
    {
      "code": "duplicate_name",
      "fix": "Pick another name.",
      "retry": false,
      "status": 409,
      "when": "A saved search or list with that name already exists."
    },
    {
      "code": "too_many_alerts",
      "fix": "Remove one first.",
      "retry": false,
      "status": 422,
      "when": "More than ten usage warnings."
    },
    {
      "code": "too_many_saved_searches",
      "fix": "Remove one first.",
      "retry": false,
      "status": 403,
      "when": "The saved search limit is reached."
    },
    {
      "code": "alert_limit_reached",
      "fix": "Turn one off, or upgrade.",
      "retry": false,
      "status": 403,
      "when": "The plan's limit of alerted saved searches is reached."
    },
    {
      "code": "watch_limit_reached",
      "fix": "Remove one, or upgrade.",
      "retry": false,
      "status": 403,
      "when": "The plan's limit of watched jobs is reached."
    },
    {
      "code": "too_many_lists",
      "fix": "Remove one first.",
      "retry": false,
      "status": 422,
      "when": "The saved list limit is reached."
    },
    {
      "code": "too_many_jobs",
      "fix": "Remove a job first.",
      "retry": false,
      "status": 422,
      "when": "A saved list is full."
    },
    {
      "code": "too_many_notes",
      "fix": "Remove one first.",
      "retry": false,
      "status": 422,
      "when": "The note limit is reached."
    },
    {
      "code": "too_many_keys",
      "fix": "Revoke a key first.",
      "retry": false,
      "status": 409,
      "when": "The account holds as many keys as it may."
    },
    {
      "code": "name_too_long",
      "fix": "Shorten it.",
      "retry": false,
      "status": 422,
      "when": "A key or account name of 80 characters or more."
    },
    {
      "code": "not_free",
      "fix": "See https://jobopportunitiesapi.org/api for the current plans.",
      "retry": false,
      "status": 409,
      "when": "The Explore plan is no longer free."
    },
    {
      "code": "no_key",
      "fix": "Create a key first.",
      "retry": false,
      "status": 409,
      "when": "An export was recorded for an account with no active key."
    },
    {
      "code": "not_allowed",
      "fix": "Use the account page you have.",
      "retry": false,
      "status": 403,
      "when": "The new account area or the free trial is not open to this account yet."
    },
    {
      "code": "could_not_start",
      "fix": "Retry later.",
      "retry": true,
      "status": 503,
      "when": "The free trial could not start. Nothing was changed."
    },
    {
      "code": "test_run_limit",
      "fix": "Retry tomorrow, or call the API with your key.",
      "retry": true,
      "status": 429,
      "when": "The day's test runs in the account area are used up."
    },
    {
      "code": "demo_disabled",
      "fix": "Use a real account.",
      "retry": false,
      "status": 409,
      "when": "The action is switched off on the demo."
    },
    {
      "code": "not_eligible",
      "fix": "Reply to the email that sent the link.",
      "retry": false,
      "status": 409,
      "when": "The key is not eligible for this offer or upgrade."
    },
    {
      "code": "invalid_link",
      "fix": "Open the link from the email again, or ask for a new one.",
      "retry": false,
      "status": 400,
      "when": "An upgrade or offer link that is not valid."
    },
    {
      "code": "link_expired",
      "fix": "Upgrade from your account page.",
      "retry": false,
      "status": 410,
      "when": "An upgrade link that has expired."
    },
    {
      "code": "offer_closed",
      "fix": "Reply to the email that sent it.",
      "retry": false,
      "status": 410,
      "when": "A personal offer that has closed."
    },
    {
      "code": "already_paid",
      "fix": "Reply to the email; the move is done by hand.",
      "retry": false,
      "status": 409,
      "when": "The key already has a paid subscription."
    },
    {
      "code": "no_such_key",
      "fix": "Reply to the email that sent it.",
      "retry": false,
      "status": 404,
      "when": "The key behind an offer link no longer exists."
    },
    {
      "code": "unknown_plan",
      "fix": "Use a plan from /public/plans.",
      "retry": false,
      "status": 422,
      "when": "There is no plan with that name."
    },
    {
      "code": "invite_only",
      "fix": "Open the link you were given.",
      "retry": false,
      "status": 422,
      "when": "The plan is offered by invitation only."
    },
    {
      "code": "plan_is_free",
      "fix": "Create the key from your account page.",
      "retry": false,
      "status": 422,
      "when": "Checkout for a free plan."
    },
    {
      "code": "plan_not_sold",
      "fix": "Choose a plan from /public/plans.",
      "retry": false,
      "status": 422,
      "when": "The plan is not sold through checkout."
    },
    {
      "code": "bad_billing",
      "fix": "Send monthly or annual.",
      "retry": false,
      "status": 422,
      "when": "billing is not monthly or annual."
    },
    {
      "code": "unknown_country",
      "fix": "Pick a country from /v1/meta/facets.",
      "retry": false,
      "status": 422,
      "when": "A country we do not publish listings for, on a country locked plan."
    },
    {
      "code": "country_not_available",
      "fix": "Leave the country out, or choose a plan that offers it.",
      "retry": false,
      "status": 422,
      "when": "A country lock on a plan that is not sold per country."
    },
    {
      "code": "continent_needs_new_key",
      "fix": "Leave the continent out, or buy the locked plan as a new key.",
      "retry": false,
      "status": 422,
      "when": "A continent lock asked for on an existing key."
    },
    {
      "code": "billing_country_required",
      "fix": "Give the country you are billed in.",
      "retry": false,
      "status": 422,
      "when": "Checkout without the billing country."
    },
    {
      "code": "company_name_required",
      "fix": "Give the registered name.",
      "retry": false,
      "status": 422,
      "when": "Business checkout without the registered company name."
    },
    {
      "code": "annual_switch_by_hand",
      "fix": "Write to support@jobopportunitiesapi.org for a personal link.",
      "retry": false,
      "status": 409,
      "when": "A running monthly subscription asked to move to annual."
    },
    {
      "code": "black_friday_switch_by_hand",
      "fix": "Write to support@jobopportunitiesapi.org for a personal link.",
      "retry": false,
      "status": 409,
      "when": "A subscription that started at the Black Friday price asked to change plan in place. Support sets the change up at the right price for the new plan; nothing was changed."
    },
    {
      "code": "sign_in_first",
      "fix": "Sign in, then choose your plan: the order goes on your account.",
      "retry": false,
      "status": 409,
      "when": "A checkout without a signed in session named the email of an account that already exists. The order goes on the account, so sign in before paying."
    },
    {
      "code": "change_plan_from_account",
      "fix": "Change the plan on https://jobopportunitiesapi.org/account/billing.",
      "retry": false,
      "status": 409,
      "when": "A signed in account that already pays asked for a checkout without naming a key. One account has one subscription, so a plan change is made from the billing page, where the same subscription is moved. Nothing was changed."
    },
    {
      "code": "account_billed_by_hand",
      "fix": "Write to support@jobopportunitiesapi.org and we will change it for you.",
      "retry": false,
      "status": 409,
      "when": "The account's plan is billed outside card checkout, so it cannot be changed there."
    },
    {
      "code": "lock_by_hand",
      "fix": "Write to support@jobopportunitiesapi.org for a personal link.",
      "retry": false,
      "status": 409,
      "when": "A country or continent locked plan was ordered for an account that already exists. The lock belongs to the account's subscription and is set up by hand."
    },
    {
      "code": "cannot_cancel",
      "fix": "Nothing to do.",
      "retry": false,
      "status": 409,
      "when": "The key has no live subscription to cancel."
    },
    {
      "code": "cannot_resume",
      "fix": "Buy the plan again.",
      "retry": false,
      "status": 409,
      "when": "The subscription has already ended."
    },
    {
      "code": "billing_unconfigured",
      "fix": "Write to support@jobopportunitiesapi.org.",
      "retry": true,
      "status": 503,
      "when": "Card checkout is not switched on."
    },
    {
      "code": "gateway",
      "fix": "Retry after a moment.",
      "retry": true,
      "status": 502,
      "when": "The payment provider could not be reached."
    },
    {
      "code": "insert_failed",
      "fix": "Retry after a moment.",
      "retry": true,
      "status": 500,
      "when": "A record could not be saved."
    },
    {
      "code": "update_failed",
      "fix": "Retry after a moment.",
      "retry": true,
      "status": 500,
      "when": "A change could not be saved."
    },
    {
      "code": "upsert_failed",
      "fix": "Retry after a moment.",
      "retry": true,
      "status": 500,
      "when": "An alert could not be saved."
    },
    {
      "code": "delete_failed",
      "fix": "Retry after a moment.",
      "retry": true,
      "status": 500,
      "when": "An item could not be deleted."
    },
    {
      "code": "store_failed",
      "fix": "Retry after a moment.",
      "retry": true,
      "status": 500,
      "when": "A mail link answer could not be recorded."
    },
    {
      "code": "order_failed",
      "fix": "Retry after a moment.",
      "retry": true,
      "status": 500,
      "when": "A dataset purchase could not start."
    },
    {
      "code": "not_on_sale",
      "fix": "Check later.",
      "retry": false,
      "status": 503,
      "when": "The dataset is not on sale yet."
    },
    {
      "code": "bad_slug",
      "fix": "Use a dataset slug from the datasets page.",
      "retry": false,
      "status": 400,
      "when": "An unknown dataset."
    },
    {
      "code": "not_paid",
      "fix": "Complete the payment.",
      "retry": false,
      "status": 403,
      "when": "The dataset order is not paid, or was refunded."
    },
    {
      "code": "expired",
      "fix": "Write to support@jobopportunitiesapi.org.",
      "retry": false,
      "status": 403,
      "when": "The dataset order's download window has closed."
    },
    {
      "code": "amount_too_small",
      "fix": "Give at least the minimum the message states.",
      "retry": false,
      "status": 422,
      "when": "A donation under the minimum."
    },
    {
      "code": "amount_too_large",
      "fix": "Use the contact form.",
      "retry": false,
      "status": 422,
      "when": "A donation above the card limit."
    },
    {
      "code": "invalid_domain",
      "fix": "Give the domain, for example example.com.",
      "retry": false,
      "status": 422,
      "when": "An opt out without a website domain."
    },
    {
      "code": "email_domain_mismatch",
      "fix": "Use an address at that domain.",
      "retry": false,
      "status": 422,
      "when": "An opt out email address not at the domain being removed."
    },
    {
      "code": "missing",
      "fix": "Send both.",
      "retry": false,
      "status": 422,
      "when": "An opt out confirmation without the domain or the code."
    },
    {
      "code": "bad_code",
      "fix": "Check the code in the email.",
      "retry": false,
      "status": 401,
      "when": "The opt out code is not correct."
    },
    {
      "code": "code_expired",
      "fix": "Request a new code.",
      "retry": false,
      "status": 410,
      "when": "The opt out code has expired."
    },
    {
      "code": "too_soon",
      "fix": "Check the inbox, or retry in a couple of minutes.",
      "retry": true,
      "status": 429,
      "when": "An opt out code was just sent."
    },
    {
      "code": "too_many_attempts",
      "fix": "Request a new code.",
      "retry": false,
      "status": 429,
      "when": "Too many wrong opt out codes."
    },
    {
      "code": "no_request",
      "fix": "Start the opt out again.",
      "retry": false,
      "status": 404,
      "when": "No pending opt out for that domain."
    },
    {
      "code": "code_failed",
      "fix": "Retry.",
      "retry": true,
      "status": 500,
      "when": "An opt out code could not be generated."
    },
    {
      "code": "verify_failed",
      "fix": "Retry.",
      "retry": true,
      "status": 500,
      "when": "An opt out could not be completed."
    },
    {
      "code": "deletion_scheduled",
      "fix": "Cancel the deletion first.",
      "retry": false,
      "status": 409,
      "when": "The account is about to be deleted."
    },
    {
      "code": "bad_phrase",
      "fix": "Type the phrase exactly as shown.",
      "retry": false,
      "status": 422,
      "when": "The account deletion confirmation phrase does not match."
    },
    {
      "code": "keys_left",
      "fix": "Revoke the keys first.",
      "retry": false,
      "status": 409,
      "when": "Account deletion with keys that are not revoked."
    },
    {
      "code": "paid_live",
      "fix": "Cancel the plan first.",
      "retry": false,
      "status": 409,
      "when": "Account deletion with a paid plan that still renews."
    },
    {
      "code": "bad_closed_reason",
      "fix": "Use expired_upstream, not_seen, apply_link_dead, employer_closed or deadline_passed.",
      "retry": false,
      "status": 422,
      "when": "An unknown closed_reason on /v1/jobs/closed."
    },
    {
      "code": "already_claimed",
      "fix": "Sign in and choose Make a secret on Keys and usage: the key keeps its plan.",
      "retry": false,
      "status": 409,
      "when": "The first key's secret was already issued, by this claim or by the owner on Keys and usage. A secret is shown exactly once; a reload of the done page lands here. Nothing new is issued."
    },
    {
      "code": "no_first_key",
      "fix": "Sign in to see your keys.",
      "retry": false,
      "status": 409,
      "when": "The payment landed when the account already had a live key, so this order created no first key (or the first key is no longer live)."
    },
    {
      "code": "order_closed",
      "fix": "If you have a question about a payment on this order, write to support@jobopportunitiesapi.org.",
      "retry": false,
      "status": 410,
      "when": "The order is closed: it expired unpaid after 24 hours, or it was refunded. No key can be claimed from a closed order."
    }
  ],
  "generated_at": "2026-11-17T07:57:27Z",
  "grammar_version": "2026-11-10",
  "help_version": "1.0.0",
  "legal_notes": {
    "notes": [
      {
        "code": "immigration_information",
        "effective_from": "2026-11-11",
        "text": "This information is not immigration advice, legal advice or any other service to candidates. It is provided for information only and may be incomplete, inaccurate or out of date. Before starting any immigration or employment process, contact a qualified, certified professional.",
        "version": "2026-11-11"
      },
      {
        "code": "nhs_jobs_source",
        "effective_from": "2026-11-11",
        "text": "These jobs come from NHS Jobs under the Open Government Licence v3.0. Review the Terms, section NHS Jobs: https://jobopportunitiesapi.org/terms#nhs-jobs",
        "version": "2026-11-11"
      }
    ],
    "summary": "Every job carries legal_note_code and legal_note: the code and the text of the legal note that goes with the row, both null when none applies. Two notes today: 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 (source nhs_jobs): those jobs are under the Open Government Licence v3.0, see the Terms, section NHS Jobs, https://jobopportunitiesapi.org/terms#nhs-jobs. When both apply, legal_note_code and legal_note carry immigration_information (the single value never changed for a row that had it) and legal_notes, a list of {code, text} on every job ([] when none applies), carries both. Every /v1/sponsors/lookup answer carries the same two keys at the top level. Information about visa sponsor registers, salary thresholds or similar rules is information only: it is not immigration or legal advice and not a service to candidates, and it may be incomplete, inaccurate or out of date. Show the legal_note with this information, unless you are an authorised immigration adviser presenting it within your regulated service. If you omit it, you take full responsibility. Terms: https://jobopportunitiesapi.org/terms"
  },
  "limits_and_quotas": {
    "comma_lists": "A list longer than its maximum is a 422 too_many_values; values are never dropped silently. country, exclude_country and state take up to 60; company_domain and exclude_company_domain up to 100; category up to 12; seniority up to 9; the rest are in the parameter table.",
    "include_description": "include_description=true caps limit at 50; above that the request is a 422 limit_too_large.",
    "include_total_budget": "The include_total count has its own 4 second budget. Past it the page is still served and total_estimate_status says timed_out. Above 10,000 matching rows it says at_least.",
    "page_size": "/v1/jobs and /v1/companies take limit 1 to 200 (default 25). Out of range is a 422 bad_limit, never a silent clamp.",
    "plan_page_cap": "A plan below the endpoint ceiling is served at its own cap, visibly: X-JOA-Limit-Applied and a Warning header.",
    "rate_limits": "Every response carries X-RateLimit-Records-Limit, X-RateLimit-Records-Remaining and X-RateLimit-Records-Reset. A 429 rate_limited carries Retry-After; retry after that many seconds.",
    "record_allowance": "Each plan has a monthly record allowance (Explore: 1,000). One record is one row returned (and one delta event). A job already charged to your key on GET /v1/jobs in the last 24 hours is not charged again. A refused request costs nothing. When the allowance is spent the answer is 402 record_quota_exhausted, which must not be retried before its resets_at.",
    "statement_timeout": "10 seconds per query. Past it the answer is a 503 with Retry-After: 5, not a 500. Narrow the filter rather than retrying unchanged: a query that is slow because of its filters times out again. When the same query, from any caller, times out again within 15 minutes the 503 carries repeated: true and Retry-After: 60.",
    "text_filters": "q, title, title_exclude, description_contains and company_name_contains must be under 500 bytes (422 filter_too_long); every value nests parentheses at most 8 levels deep (422 query_too_complex); a boolean expression holds at most 32 terms (422 query_too_complex), a plain value has no such limit, except on company_name_contains, whose values are always parsed as expressions (there the limits apply and the refusal comes after the meter check but before any charge) and must contain a word or number (422 query_has_no_terms). description_contains searches live postings only: with status=closed or any, on /v1/jobs/closed and /v1/jobs/expired it answers 422 description_contains_live_only."
  },
  "links": {
    "changelog": "https://jobopportunitiesapi.org/changelog",
    "coverage": "https://api.jobopportunitiesapi.org/public/coverage",
    "documentation": "https://jobopportunitiesapi.org/docs",
    "error_reference": "https://jobopportunitiesapi.org/docs/api/errors",
    "facets": "https://api.jobopportunitiesapi.org/public/facets",
    "for_agents": "https://jobopportunitiesapi.org/for/ai-agents",
    "integration_brief": "https://api.jobopportunitiesapi.org/public/ai-prompt",
    "machine_readable_docs": "https://jobopportunitiesapi.org/docs/ai/index.md",
    "openapi": "https://api.jobopportunitiesapi.org/public/openapi.json",
    "parameter_reference": "https://jobopportunitiesapi.org/docs/api/parameters",
    "providers": "https://api.jobopportunitiesapi.org/public/providers",
    "query_grammar": "https://jobopportunitiesapi.org/docs/api/filtering#query-grammar"
  },
  "parameters": [
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/companies",
        "/v1/export",
        "/v1/jobs/closed"
      ],
      "example": "q=nurse OR midwife",
      "name": "q",
      "summary": "Free text over title, company name and location (companies: over the name). Takes the query grammar.",
      "type": "string"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/jobs/closed",
        "/v1/export"
      ],
      "example": "title=%22change%20manager%22",
      "name": "title",
      "summary": "Words in the job title only. Takes the query grammar. Fantastic.jobs alias: title_advanced.",
      "type": "string"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/jobs/closed",
        "/v1/export"
      ],
      "example": "title_exclude=sales",
      "name": "title_exclude",
      "summary": "Exclude rows whose title matches. Takes the query grammar.",
      "type": "string"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/jobs/closed",
        "/v1/export"
      ],
      "example": "company_name_contains=Siemens%20%7C%20Bosch",
      "name": "company_name_contains",
      "summary": "Boolean text search on the employer name, e.g. Siemens | Bosch or !(Amazon | Meta). Takes the query grammar; every value is read by it. Fantastic.jobs alias: organization_advanced.",
      "type": "string"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/export"
      ],
      "example": "description_contains=kubernetes&country=DE",
      "name": "description_contains",
      "summary": "Words in the advert body only. The expensive one: narrow it with a country. Takes the query grammar. Fantastic.jobs alias: description_advanced (theirs also searches the title).",
      "type": "string"
    },
    {
      "endpoints": [
        "*",
        "/v1/jobs/withdrawn",
        "/v1/jobs/similar"
      ],
      "example": "country=DE,AT,CH",
      "name": "country",
      "summary": "ISO 3166-1 alpha-2 codes, comma separated, up to 60. Unknown codes are a 422 bad_country.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/export"
      ],
      "example": "exclude_country=US",
      "name": "exclude_country",
      "summary": "Countries to leave out. Rows with no country are kept.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/sponsors/lookup"
      ],
      "example": "region=GB-DEV,GB-CON",
      "name": "region",
      "summary": "ISO 3166-2 subdivision codes or English names, comma separated, up to 60: GB-DEV or Devon, US-OH or Ohio, CA-ON, AU-WA. Covers US states, Canadian provinces, Australian states and territories, UK nations and about 50 UK counties. Rows whose region is not established are never returned by a region filter and never excluded by other filters. Unknown values are a 422 bad_region. On /v1/sponsors/lookup: one US state for the US registers, two letters or in full (region=CA or region=California).",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "state=CA,NY",
      "name": "state",
      "summary": "US state or CA province codes, up to 60.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "city=Berlin",
      "name": "city",
      "summary": "City names as /public/facets publishes them, up to 12. Case is ignored, and accents for most cities: Medellin also finds Medellín (since 12 Nov 2026). For the largest cities type the accents as stored (São Paulo).",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/export",
        "/v1/jobs/closed",
        "/v1/jobs/similar"
      ],
      "example": "category=Engineering,Healthcare",
      "name": "category",
      "summary": "Job family from the controlled vocabulary, up to 12. An unknown value is a 422 bad_category.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/public/market-signals"
      ],
      "example": "family=healthcare",
      "name": "family",
      "summary": "The same vocabulary as category on the market-signals surface, up to 12.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "exclude_category=Sales",
      "name": "exclude_category",
      "summary": "Categories to leave out, up to 12.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "company=but",
      "name": "company",
      "summary": "Company slugs, up to 8.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/export"
      ],
      "example": "company_domain=stripe.com,figma.com",
      "name": "company_domain",
      "summary": "Employer web domains, up to 100. The stable identity key for a company.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "exclude_company_domain=agency.example",
      "name": "exclude_company_domain",
      "summary": "Employer domains to leave out, up to 100.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/export",
        "/v1/jobs/closed"
      ],
      "example": "provider=greenhouse,lever",
      "name": "provider",
      "summary": "Source slugs from /public/providers or /v1/meta/providers, up to 12. Unknown slugs are a 422 bad_provider.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "exclude_provider=workday",
      "name": "exclude_provider",
      "summary": "Sources to leave out, up to 12.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/companies",
        "/v1/export"
      ],
      "example": "source_type=career_site",
      "name": "source_type",
      "summary": "career_site or jobboard, up to 6.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "exclude_source_type=jobboard",
      "name": "exclude_source_type",
      "summary": "Source buckets to leave out.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "employment_type=Full-time",
      "name": "employment_type",
      "summary": "Full-time, Part-time, Contract, Internship, Temporary, not_stated (any case; full_time and part_time are accepted too). Up to 6.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/public/market-signals"
      ],
      "example": "seniority=Senior,Lead",
      "name": "seniority",
      "summary": "Intern, Entry, Mid, Senior, Lead, Manager, Director, Executive, not_stated (any case; not_stated selects rows with none). The levels our classifier reads off the title, so always inferred. Up to 9.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/jobs/similar"
      ],
      "example": "remote=remote,hybrid",
      "name": "remote",
      "summary": "remote, hybrid, on_site, not_stated (any case). Up to 4.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "remote_confirmed=true",
      "name": "remote_confirmed",
      "summary": "true keeps only rows whose employer states the remote policy.",
      "type": "bool"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "language=de,nl",
      "name": "language",
      "summary": "Listing language codes, up to 12.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "language_exclude=en",
      "name": "language_exclude",
      "summary": "Languages to leave out.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/export"
      ],
      "example": "has_salary=true",
      "name": "has_salary",
      "summary": "true (or structured) keeps rows with a published or structured salary; any keeps every row that can show a figure; false keeps rows without one.",
      "type": "enum"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/export"
      ],
      "example": "min_salary=60000",
      "name": "min_salary",
      "summary": "Annual EUR floor, 0 to 10,000,000.",
      "type": "number"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/export"
      ],
      "example": "max_salary=120000",
      "name": "max_salary",
      "summary": "Annual EUR ceiling.",
      "type": "number"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "compensation_type=salary",
      "name": "compensation_type",
      "summary": "salary, commission, tips, equity. Up to 4.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "exclude_compensation_type=commission",
      "name": "exclude_compensation_type",
      "summary": "Compensation types to leave out.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "country_confidence=high",
      "name": "country_confidence",
      "summary": "high or low: how certain the country of a row is.",
      "type": "enum"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/export",
        "/v1/me/export-estimate"
      ],
      "example": "require_fields=salary,description",
      "name": "require_fields",
      "summary": "Keep only rows that carry these fields (salary, location, description and the rest), up to 13.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "has_description=true",
      "name": "has_description",
      "summary": "true keeps only rows that have an advert body.",
      "type": "bool"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/jobs/similar"
      ],
      "example": "include_description=true&limit=10",
      "name": "include_description",
      "summary": "Add the advert body to each row. Caps limit at 50 (a bigger request is a 422 limit_too_large).",
      "type": "bool"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "include_poster_type=staffing,jobboard",
      "name": "include_poster_type",
      "summary": "staffing, jobboard or all: re-admit rows held as agency or board postings. /v1 only.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "quality=all",
      "name": "quality",
      "summary": "all re-admits rows the quality gate holds back (never rows it removed). /v1 only.",
      "type": "enum"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/export"
      ],
      "example": "status=any",
      "name": "status",
      "summary": "live (default), closed or any.",
      "type": "enum"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "collapse=company",
      "name": "collapse",
      "summary": "company returns at most one row per employer per page and counts the hidden roles on it.",
      "type": "enum"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "max_per_company=3",
      "name": "max_per_company",
      "summary": "Cap one employer at N rows per page, 1 to 200.",
      "type": "integer"
    },
    {
      "endpoints": [
        "*",
        "/v1/jobs/withdrawn",
        "/v1/jobs/similar"
      ],
      "example": "limit=25",
      "name": "limit",
      "summary": "Page size. /v1 1 to 200 (default 25); /public 1 to 50. Out of range is a 422 bad_limit.",
      "type": "integer"
    },
    {
      "endpoints": [
        "*"
      ],
      "example": "cursor=<next_cursor>",
      "name": "cursor",
      "summary": "The next_cursor of the previous page, verbatim. Never parse it.",
      "type": "string"
    },
    {
      "endpoints": [
        "/v1/companies",
        "/v1/jobs"
      ],
      "example": "offset=50",
      "name": "offset",
      "summary": "Offset paging, on the company directory only. On /v1/jobs a non-zero offset is a 422 offset_not_supported.",
      "type": "integer"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "include_total=true",
      "name": "include_total",
      "summary": "Add total_estimate and total_estimate_status (exact, at_least above 10,000, or timed_out).",
      "type": "bool"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "sort=relevance",
      "name": "sort",
      "summary": "relevance, when ranked search is enabled on the deployment; otherwise 422 sort_unavailable.",
      "type": "enum"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/jobs/closed",
        "/v1/export",
        "/v1/jobs/similar"
      ],
      "example": "listed_after=2026-10-24T00:00:00Z",
      "name": "listed_after",
      "summary": "Rows that entered the API after this instant. The right parameter for an incremental import (since does the same with no overlap). Every time filter also takes a relative value: now, now-15m, now-2h, now-1d, today, yesterday (UTC).",
      "type": "timestamp"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/jobs/closed",
        "/v1/export",
        "/v1/jobs/similar"
      ],
      "example": "listed_after=yesterday&listed_before=today",
      "name": "listed_before",
      "summary": "Rows that entered the API before this instant (exclusive). With listed_after, a range.",
      "type": "timestamp"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/export"
      ],
      "example": "posted_before=2026-11-01",
      "name": "posted_before",
      "summary": "The employer's own posting date, before this instant (exclusive). With posted_after, a range.",
      "type": "timestamp"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "verified_before=now-7d",
      "name": "verified_before",
      "summary": "Rows last positively confirmed at their source before this instant (exclusive). With verified_after, a range.",
      "type": "timestamp"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/export"
      ],
      "example": "posted_after=2026-10-01",
      "name": "posted_after",
      "summary": "The employer's own posting date, after this instant. Runs behind listed_after.",
      "type": "timestamp"
    },
    {
      "endpoints": [
        "/v1/jobs"
      ],
      "example": "verified_after=2026-10-20T00:00:00Z",
      "name": "verified_after",
      "summary": "Rows positively confirmed at their source after this instant.",
      "type": "timestamp"
    },
    {
      "endpoints": [
        "/v1/changes",
        "/v1/jobs/expired",
        "/v1/jobs/withdrawn",
        "/v1/jobs",
        "/v1/jobs/closed"
      ],
      "example": "since=2026-10-24T00:00:00Z",
      "name": "since",
      "summary": "Where a delta walk resumes. Use the cursor the response gives you. On /v1/jobs and /v1/jobs/closed it is the resumable poll: the first call takes a time (now-1d, an RFC3339 timestamp), every page returns next_since, and the next poll sends it back: no gap, no duplicate.",
      "type": "timestamp"
    },
    {
      "endpoints": [
        "/v1/export"
      ],
      "example": "after=<last id>",
      "name": "after",
      "summary": "Resume an export after this id, instead of starting again.",
      "type": "string"
    },
    {
      "endpoints": [
        "/v1/jobs/closed"
      ],
      "example": "closed_after=2026-10-01",
      "name": "closed_after",
      "summary": "Roles that closed at or after this instant.",
      "type": "timestamp"
    },
    {
      "endpoints": [
        "/v1/jobs/closed"
      ],
      "example": "closed_before=2026-10-15",
      "name": "closed_before",
      "summary": "Roles that closed before this instant.",
      "type": "timestamp"
    },
    {
      "endpoints": [
        "/v1/jobs/closed"
      ],
      "example": "closed_reason=expired_upstream",
      "name": "closed_reason",
      "summary": "expired_upstream, not_seen, apply_link_dead, employer_closed, deadline_passed. Up to 3.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs/{id}"
      ],
      "example": "include_closed=true",
      "name": "include_closed",
      "summary": "Let a job lookup resolve a role that has closed. GET /v1/jobs (the list) refuses it with 400 unsupported_parameter: for closed roles in a list use GET /v1/jobs/closed, or status=any (live and closed) or status=closed on /v1/jobs.",
      "type": "bool"
    },
    {
      "endpoints": [
        "/v1/jobs/{id}",
        "/v1/export-packs/{id}"
      ],
      "example": "41737220-e01e-43d2-96b0-281b0906161d",
      "name": "id",
      "summary": "The row's UUID, in the path.",
      "type": "string"
    },
    {
      "endpoints": [
        "/v1/companies/{slug}"
      ],
      "example": "but",
      "name": "slug",
      "summary": "A company slug. Retired slugs 301 to their replacement.",
      "type": "string"
    },
    {
      "endpoints": [
        "/v1/companies"
      ],
      "example": "org_type=private",
      "name": "org_type",
      "summary": "Employer organisation type, on the company directory only.",
      "type": "enum"
    },
    {
      "endpoints": [
        "/v1/companies"
      ],
      "example": "has_website=true",
      "name": "has_website",
      "summary": "Keep only employers with a website of their own. Companies only.",
      "type": "bool"
    },
    {
      "endpoints": [
        "/v1/companies"
      ],
      "example": "include_discovered=true",
      "name": "include_discovered",
      "summary": "Include employers discovered but not yet verified. Companies only.",
      "type": "bool"
    },
    {
      "endpoints": [
        "/public/market-signals/history",
        "/public/companies/{slug}/open-roles-history",
        "/v1/me/usage"
      ],
      "example": "days=90",
      "name": "days",
      "summary": "Window length in days for a history series.",
      "type": "integer"
    },
    {
      "endpoints": [
        "/v1/me/usage"
      ],
      "example": "metric=records",
      "name": "metric",
      "summary": "Which usage metric to read.",
      "type": "string"
    },
    {
      "endpoints": [
        "/public/quote"
      ],
      "example": "plan=signal",
      "name": "plan",
      "summary": "Which plan to price.",
      "type": "string"
    },
    {
      "endpoints": [
        "/public/quote",
        "/public/vat/check"
      ],
      "example": "vat_number=DE123456789",
      "name": "vat_number",
      "summary": "An EU VAT number, for the reverse charge decision.",
      "type": "string"
    },
    {
      "endpoints": [
        "/public/sitemap/{kind}/{page}",
        "/public/lifecycle-unsubscribe"
      ],
      "example": "kind=jobs",
      "name": "kind",
      "summary": "Sitemap family, or which product email to leave.",
      "type": "string"
    },
    {
      "endpoints": [
        "/o/{code}"
      ],
      "example": "K7M2Q",
      "name": "code",
      "summary": "The short code of a personalised offer, in the path.",
      "type": "string"
    },
    {
      "endpoints": [
        "/offer/{token}",
        "/public/invoice/{token}",
        "/public/upgrade/checkout",
        "/public/offer/checkout"
      ],
      "example": "<from the link>",
      "name": "token",
      "summary": "A signed token from a mail or an offer link, in the path or the body. It is the whole credential: never log it.",
      "type": "string"
    },
    {
      "endpoints": [
        "/public/unsubscribe",
        "/public/lifecycle-unsubscribe",
        "/public/welcome-intent",
        "/public/month-rating"
      ],
      "example": "<from the mail>",
      "name": "tok",
      "summary": "The second half of a mailed two-part token, paired with id. Proves the mail reached the address.",
      "type": "string"
    },
    {
      "endpoints": [
        "/public/checkout/status"
      ],
      "example": "<from the checkout redirect>",
      "name": "exp",
      "summary": "The checkout token whose outcome to read.",
      "type": "string"
    },
    {
      "endpoints": [
        "/public/confirm"
      ],
      "example": "you@example.com",
      "name": "e",
      "summary": "The address being confirmed, in the mailed link.",
      "type": "string"
    },
    {
      "endpoints": [
        "/public/confirm"
      ],
      "example": "<from the mail>",
      "name": "t",
      "summary": "The confirmation token in the mailed link.",
      "type": "string"
    },
    {
      "endpoints": [
        "/public/sitemap/{kind}/{page}"
      ],
      "example": "1",
      "name": "page",
      "summary": "Which sitemap chunk, numbered from 1.",
      "type": "integer"
    },
    {
      "endpoints": [
        "/v1/jobs/similar"
      ],
      "example": "job_id=3cf28c2c-10e3-44b7-877f-e66fa3d304ee",
      "name": "job_id",
      "summary": "The job whose stored vector is the query (more like this). The job itself is never in the results.",
      "type": "uuid or slug"
    },
    {
      "endpoints": [
        "/v1/jobs/similar"
      ],
      "example": "min_score=0.6",
      "name": "min_score",
      "summary": "Drop results whose cosine similarity is below this value.",
      "type": "number -1..1"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/jobs/{id}",
        "/v1/changes",
        "/v1/jobs/similar"
      ],
      "example": "include=embedding",
      "name": "include",
      "summary": "Opt-in extras. include=embedding adds the 1024 dimension Qwen3-Embedding-8B document vector (limit at most 100).",
      "type": "comma list"
    },
    {
      "endpoints": [
        "/v1/sponsors/lookup"
      ],
      "example": "name=Rolls-Royce",
      "name": "name",
      "summary": "The employer name to look up on the sponsor registers, legal or trading name, as you hold it. Required on GET /v1/sponsors/lookup.",
      "type": "string"
    },
    {
      "endpoints": [
        "/v1/sponsors/lookup"
      ],
      "example": "town=Derby",
      "name": "town",
      "summary": "The employer's town or city: resolves a name that several legal entities share to the one registered there (US: send region too).",
      "type": "string"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/jobs/closed",
        "/v1/jobs/similar",
        "/v1/export"
      ],
      "example": "country=US&country_match=any",
      "name": "country_match",
      "summary": "primary (default) or any. Some jobs are open to several countries and list them in countries. primary compares country, exclude_country and a locked key's country with the job's country only; any compares every country in countries. Since 8 Nov 2026.",
      "type": "enum"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/jobs/closed",
        "/v1/jobs/similar",
        "/v1/export"
      ],
      "example": "sponsor_register=GB,NL",
      "name": "sponsor_register",
      "summary": "Only jobs whose employer is on an official sponsor or work permit register of these countries: GB (UK accepted), NL, US, CA, IE, DK, or any. A register counts only for jobs located in (or open to) its country. Being on a register is a public fact as of the register's date, not a promise to sponsor a visa. Other values are a 422 bad_sponsor_register. Since 10 Nov 2026.",
      "type": "comma list"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/jobs/closed",
        "/v1/jobs/similar",
        "/v1/export"
      ],
      "example": "country=DE&visa_text=stated_open",
      "name": "visa_text",
      "summary": "stated_open or stated_closed: only jobs whose work_visa_text.evidence_level is this value, that is what the advert itself says (quoted word for word). Jobs not read (not_assessed) never match; work_visa_text.coverage lists the countries read. It selects what adverts say: not advice and not a decision on any person's case. Anything else is a 422 bad_visa_text.",
      "type": "enum"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/jobs/closed",
        "/v1/jobs/similar",
        "/v1/export"
      ],
      "example": "engagement=vendor",
      "name": "engagement",
      "summary": "employee, vendor, other, unknown (alias not_stated), up to 8: the employment relationship the posting states. unknown selects rows where the posting does not establish it (most rows). Unknown values are a 422 bad_engagement.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/jobs/closed",
        "/v1/jobs/similar",
        "/v1/export"
      ],
      "example": "contract_category=permanent",
      "name": "contract_category",
      "summary": "permanent, fixed_term, project_based, seasonal, apprenticeship, internship, other, unknown (alias not_stated), up to 8: the contract kind the posting states. permanent returns only postings that state permanence. Unknown values are a 422 bad_contract_category.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/jobs/closed",
        "/v1/jobs/similar",
        "/v1/export"
      ],
      "example": "agency=direct",
      "name": "agency",
      "summary": "direct, agency, umbrella, unknown (alias not_stated), up to 8: who the employer of record is. Unknown values are a 422 bad_agency.",
      "type": "list"
    },
    {
      "endpoints": [
        "/v1/jobs",
        "/v1/jobs/closed",
        "/v1/jobs/similar",
        "/v1/export"
      ],
      "example": "working_schedule=part_time",
      "name": "working_schedule",
      "summary": "full_time, part_time, flexible, unknown (alias not_stated), up to 8: the schedule the posting states. Distinct from employment_type. Unknown values are a 422 bad_working_schedule.",
      "type": "list"
    }
  ],
  "query_grammar": {
    "applies_to": [
      "q",
      "title",
      "title_exclude",
      "description_contains",
      "company_name_contains"
    ],
    "fantastic_jobs": {
      "guide": "https://jobopportunitiesapi.org/docs/moving-from-fantastic-jobs",
      "note": "Fantastic.jobs parameter names are accepted as aliases on /v1/jobs, /v1/jobs/closed, /v1/jobs/similar and /v1/export: title_advanced (and advanced_title_filter, title_filter) is title; description_advanced (advanced_description_filter, description_filter) is description_contains, which searches the advert text only and live postings only, while theirs also searches the title; organization_advanced (advanced_organization_filter) is company_name_contains. location_advanced is refused with a 400 naming country, city, state and region. Malformed queries are a 422 here and a 400 there."
    },
    "operators": [
      {
        "input": "\"change manager\"  or  'change manager'",
        "means": "A phrase: the words adjacent and in order. A one-word quote is an exact word."
      },
      {
        "input": "change",
        "means": "A bare term is always the exact word (case and accent folded). Since 10 Nov 2026 there is no automatic prefix: until then a bare term of five or more letters also matched longer words once any grammar was used, so react OR vue matched Reactor."
      },
      {
        "input": "change*  or  change:*",
        "means": "Explicit prefix on the last word of the term. The prefix needs at least 3 letters or digits. 'project manag':* prefixes the last word of a phrase."
      },
      {
        "input": "a b  or  a AND b  or  a & b",
        "means": "Both terms in the field, in any order, at any distance."
      },
      {
        "input": "a OR b  or  a | b",
        "means": "Either alternative. OR joins whole AND groups: a b OR c d is (a b) OR (c d)."
      },
      {
        "input": "(a OR b) c",
        "means": "Parentheses group. They decide what an OR binds to."
      },
      {
        "input": "-berlin  or  !berlin  or  NOT berlin",
        "means": "Exclude rows matching the next term, phrase or group. - and ! must touch it: a free standing one is punctuation."
      },
      {
        "input": "a OR b -c",
        "means": "NOT binds tightest and joins the AND group it sits in: a OR (b AND NOT c). Write (a OR b) -c for the other reading."
      },
      {
        "input": "-(a OR b)  or  !(a | b)",
        "means": "Exclude the whole group."
      },
      {
        "input": "machine <-> learning",
        "means": "Followed by: the second term right after the first."
      },
      {
        "input": "data <2> scientist",
        "means": "Followed by within N positions, N from 1 to 10."
      },
      {
        "input": "Shift Lead | Philadelphia",
        "means": "& and | are operators only when every pair of terms is joined by an operator, or the value uses other grammar. In a pasted title like this they are punctuation and the value stays a plain word search. R&D and FP&A are one word."
      }
    ],
    "precedence": [
      "1. parentheses, tightest",
      "2. NOT (NOT, - or ! touching the term or group)",
      "3. followed by (<-> or <N>)",
      "4. AND (a space, AND or &)",
      "5. OR (OR or |), loosest"
    ],
    "precedence_example": {
      "input": "a b OR c d",
      "not": "a AND (b OR c) AND d",
      "note": "OR binds loosest since 25 Oct 2026; before that date this query read as a AND (b OR c) AND d. a | b & c is a | (b & c).",
      "parses_as": "(a b) OR (c d)"
    },
    "punctuation": "Commas, plus signs and other punctuation between words are word separators, not syntax, and are ignored. & and | are operators under the rule above.",
    "refuse_with_422_query_syntax": [
      {
        "input": "nurse (rn",
        "why": "unmatched '(': it is never closed before the end of the query (at character 7)"
      },
      {
        "input": "()",
        "why": "empty parentheses: a group needs at least one word or phrase"
      },
      {
        "input": "a OR",
        "why": "OR needs a word or phrase on its right"
      },
      {
        "input": "react | vue |",
        "why": "'|' needs a word or phrase on its right. A single word with a dangling | or & (Philadelphia |) is not refused: it is the plain search of that word."
      },
      {
        "input": "(react | vue) &",
        "why": "'&' needs a word or phrase on its right"
      },
      {
        "input": "a <0> b",
        "why": "a FOLLOWED BY distance must be from 1 to 10"
      }
    ],
    "refuse_with_422_query_too_complex": [
      {
        "input": "more than 32 words or phrases in one value",
        "why": "too many terms"
      },
      {
        "input": "parentheses nested more than 8 deep",
        "why": "too deep"
      },
      {
        "input": "ab*",
        "why": "a prefix needs at least 3 letters or digits"
      }
    ],
    "refuse_with_422_query_too_complex_note": "The term and prefix limits apply to boolean expressions only. A plain value (no operator, quote, parenthesis or wildcard) has no term limit, as before 10 Nov 2026. The 500 byte limit and the 8 level parenthesis limit apply to every value (the parenthesis limit since 11 Nov 2026).",
    "refused_by_the_strict_checks": [
      {
        "code": "filter_too_long",
        "input": "any text filter of 500 bytes or more (200 until 10 Nov 2026)"
      },
      {
        "code": "query_has_no_terms",
        "input": "a value that is only operators and punctuation"
      }
    ],
    "summary": "These values are not plain strings. A value that uses any of the grammar (quotes, OR / AND / NOT, a trailing * or :*, an attached - or !, <-> or <N>, or parentheses) is parsed as a boolean query. A value that uses none of it is a plain word search, exactly as before. The Fantastic.jobs _advanced notation (& | ! :* <-> 'phrase') is part of the same grammar, so their expressions paste unchanged.",
    "version": "2026-11-10",
    "worked_examples": [
      {
        "measured": "2026-10-25",
        "question": "Titles with the exact two word phrase",
        "request": "title=%22change%20manager%22&country=GB",
        "rows": 29
      },
      {
        "measured": "2026-10-25",
        "question": "Titles with both words, any order",
        "request": "title=%22change%22%20%22manager%22&country=GB",
        "rows": 47
      },
      {
        "measured": "2026-10-25",
        "note": "The same query before 25 Oct 2026 returned 1 row.",
        "question": "Four word pair alternatives, the query that started this",
        "request": "title=%22change%22%20%22lead%22%20OR%20%22change%22%20%22manager%22%20OR%20%22training%22%20%22lead%22%20OR%20%22training%22%20%22manager%22&country=GB",
        "rows": 88
      },
      {
        "measured": "2026-10-25",
        "note": "Before 25 Oct 2026 the parentheses were dropped and this returned 0 rows.",
        "question": "The same query with parentheses on each pair",
        "request": "title=(%22change%22%20%22lead%22)%20OR%20(%22change%22%20%22manager%22)%20OR%20(%22training%22%20%22lead%22)%20OR%20(%22training%22%20%22manager%22)&country=GB",
        "rows": 88
      },
      {
        "measured": "2026-10-25",
        "question": "Two alternatives of two words each",
        "request": "title=%22change%22%20%22lead%22%20OR%20%22change%22%20%22manager%22&country=GB",
        "rows": 58
      }
    ]
  },
  "visa_checks": {
    "countries": [
      "DK",
      "GB",
      "IE",
      "NL"
    ],
    "docs": "https://jobopportunitiesapi.org/docs/api/fields-and-values",
    "flags": [
      "hours_assumed_37_5",
      "below_national_living_wage"
    ],
    "occupation_statuses": [
      "on_skilled_list",
      "on_list_in_country_only",
      "on_list_transitional_only",
      "not_on_skilled_list",
      "occupation_unknown",
      "not_assessed"
    ],
    "salary_reasons": [
      "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"
    ],
    "salary_statuses": [
      "at_or_above_general_threshold",
      "at_or_above_reduced_threshold_only",
      "below_published_thresholds",
      "salary_not_comparable"
    ],
    "summary": "Every job carries visa_checks (added 11 Nov 2026). For a job in GB, IE, NL or DK it holds one object with two factual checks of the advert against the official published rules of the country's main work route, each with its sources and dates: occupation_check (is the occupation on the official list of the route) and salary_check (how the advertised pay compares with the official thresholds). They describe facts and sources only. They are not advice and not a decision on any person's case: whether a visa or permit is granted depends on the person, the employer and the authority. The same facts for every reader. Computed daily from the advert title and the published salary; an occupation code is used only when the title exactly matches an entry of the ONS SOC 2020 coding index (GB, IE) or JOA's ISCO-08 code for the title (DK). Irish checks are shown only while JOA's daily check finds the DETE occupation lists unchanged. [] for jobs in other countries, for a job not checked yet, and when the field is switched off. No filter and no metering change. A job with a non-empty visa_checks carries the legal note immigration_information. Pay is compared only when it is stated by the job's own salary fields as hourly, monthly or yearly and fits that period: pay read from the page's structured data gives salary_not_comparable with reason pay_source_unverified, weekly or daily pay gives pay_period_not_supported, and an amount that does not fit its stated period (for example an hourly figure labelled monthly) gives pay_period_implausible. 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)."
  },
  "work_visa_text": {
    "codes": [
      "text_permit_support",
      "text_relocation_support",
      "text_permit_required",
      "text_no_sponsorship",
      "text_citizenship_restriction"
    ],
    "coverage": {
      "countries": [
        "DE",
        "FR",
        "IT"
      ],
      "meaning": "Jobs in these countries that were live when they were read, up to read_by. Jobs first seen later, or changed since they were read, read not_assessed until they are read again.",
      "read_by": "2026-11-14"
    },
    "docs": "https://jobopportunitiesapi.org/docs/api/work-visa-text",
    "evidence_levels": [
      "stated_open",
      "stated_closed",
      "no_information",
      "not_assessed"
    ],
    "filter_values": [
      "stated_open",
      "stated_closed"
    ],
    "methods": [
      "published_by_employer"
    ],
    "summary": "Every job carries work_visa_text: what the advert itself says about visa sponsorship, work permits, relocation and the right to work. statements lists each statement found, with a code and a quote copied word for word from the employer's advert in its original language (never translated or corrected), quote_lang and method published_by_employer. evidence_level follows a fixed rule over the codes: stated_closed when a statement is text_no_sponsorship, text_permit_required or text_citizenship_restriction (this wins over every other statement), stated_open when a statement is text_permit_support and none closes the job, no_information when the advert was read and has no such statement (or only text_relocation_support), not_assessed when there is no current reading (the job was not read, its title or text changed since it was read: JOA compares a hash of the exact text that was read, byte for byte, and a change of any other field does not count; a quote cannot be shown exactly as written; or the field is switched off). Adverts longer than 8,000 characters are read as their first 5,000 and last 3,000 characters. It describes the advert: it is not advice and not a decision on any person's case, and it says nothing about whether a visa or permit is granted. Most adverts say nothing of this kind, also at employers that hire from abroad, so no_information means the advert is silent, not that the employer refuses. The codes are JOA's reading (a language model finds and codes the statements; code checks that every quote is found exactly in the advert); the quotes are the employer's words. method_version names the reading method and as_of the day it was read. coverage below lists the countries read and the day; every other job reads not_assessed. Filter: visa_text=stated_open or visa_text=stated_closed. No metering change. A job whose work_visa_text carries a statement carries the legal note immigration_information."
  }
}
