Filtering cookbook

Prefix any of these with the endpoint: https://api.jobopportunitiesapi.org/v1/jobs, with your key. There is no keyless row tier anymore: /public/jobs answered these until PUBLIC_LISTINGS_GATE and now needs a key too (see Keyless access). All four paid-only parameters in the parameter reference are honoured on /v1.

?country=DE&category=Engineering means German and engineering. ?country=DE,AT means German or Austrian. Those are the only two combinators, and knowing that is most of what you need to predict a result set.

There is no OR across parameters: you cannot ask for “engineering roles in Germany or any role in Austria” in one request. Send two requests and merge. That is a deliberate limit: an expression language over 34 parameters would be a query planner's problem and a support burden, and two requests cost two records more than one.

Everything else can only be included. If you need “not senior”, ask for the seniorities you do want, or fetch and filter your side: the vocabulary is small and enumerable.

Looking for a role by name

title=engineer. Narrowest and cheapest of the three.

Looking for a company or a place

q=berlin. q covers title, company name and location together.

Looking for a skill or a technology

description_contains=kubernetes. Only this one reads the advert body.

Excluding a kind of role

title_exclude=sales alongside title=engineer.

The value of title, title_exclude, description_contains and q is not a plain string. It is a small grammar: quotes, adjacency, OR, parentheses, * and a leading dash. Every behaviour on this page is what the parser actually does, re-checked against the live API on 25 October 2026.

The precedence, stated once: parentheses first, adjacency (an implicit AND) next, `OR` last. So a b OR c d is (a b) OR (c d), and four word pairs written one after the other really are four alternatives.

a b OR c d    is    (a b) OR (c d)

Start with the case that prompted this change. A customer sent this, meaning four word pairs: "change lead", "change manager", "training lead", "training manager":

curl -s -H "Authorization: Bearer $JOA_KEY" --get \
  https://api.jobopportunitiesapi.org/v1/jobs \
  --data-urlencode 'title="change" "lead" OR "change" "manager" OR "training" "lead" OR "training" "manager"' \
  --data-urlencode 'country=GB' \
  --data-urlencode 'include_total=true' --data-urlencode 'limit=1'

It returns 88 rows. Until 25 October 2026 it returned 1 (2 on the day the customer ran it), and the query was not wrong: the grammar did not mean what it looked like. OR used to bind TIGHTER than adjacency, so that line parsed as:

change AND (lead OR change) AND (manager OR training) AND (lead OR training) AND manager

which simplifies to a title containing change and manager and either lead or training. One narrow thing, not four alternatives. Today the same request is the union of the four pairs: 12 + 47 + 10 + 21 titles, two of which are in common, which is the 88.

Parentheses are grouping now, so the same query can say what it means. The same request with a parenthesis around each pair returns the same 88 rows. Until 25 October parentheses were dropped as punctuation, dropping them broke the pairing, and that version returned 0 rows with no word about it. That silent zero is the trap behind most "my query returns nothing" reports, and it is why the parser now refuses what it cannot honour instead of dropping it.

curl -s -H "Authorization: Bearer $JOA_KEY" --get \
  https://api.jobopportunitiesapi.org/v1/jobs \
  --data-urlencode 'title=("change" "lead") OR ("change" "manager") OR ("training" "lead") OR ("training" "manager")' \
  --data-urlencode 'country=GB' \
  --data-urlencode 'include_total=true' --data-urlencode 'limit=1'

There is a ten-second statement timeout. Cross it and you get a 503 with Retry-After, not a 500: the failure is honest and retryable. But retrying an expensive query unchanged mostly produces another timeout, so the useful response is to narrow it.

1. Add a country. The cheapest and most effective narrowing available.
2. Add a category, or a provider. Both are indexed and both cut the candidate set hard.
3. Drop the second full-text filter. title and description_contains together are the pathological case: both indexes are GIN and the matching rows still have to be fetched to be ordered by posted_at.
4. Reduce `require_fields`. Each additional required field is another condition over the provenance block.
5. Lower `limit`. Less to fetch and less to serialise, and fewer records charged.