Filtering jobs

Every filter on /v1/jobs is a query parameter. Separate parameters combine with AND; within one parameter, a comma means OR — with a single exception, skill, where a comma stays AND. The same filter set drives /v1/jobs/count when you want the number without the rows.

# Remote Python roles in the US or Canada, posted in the last week, with a salary.
curl -G https://api.hyperjobs.io/v1/jobs \
  -H "Authorization: Bearer $HYPERJOBS_KEY" \
  --data-urlencode "skill=python" \
  --data-urlencode "work_arrangement=Remote" \
  --data-urlencode "country=US,Canada" \
  --data-urlencode "has_salary=true" \
  --data-urlencode "time_frame=7d"

Bad input is a 400#

Every parameter name and value is validated. An unknown parameter, an empty value, a misspelled enum member, an unrecognised ISO code — each returns 400 {"error": "invalid request", "param": "…", "hint": "…"} naming the offending parameter — nothing is silently dropped.

The practical consequence: an empty result set means nothing matched. A typo'd filter can never masquerade as "no jobs found" — a request that only "works" by ignoring a bad parameter fails loudly instead. See errors.

Always applied#

Two conditions are on every /v1/jobs query and can't be turned off:

• Duplicates are excluded. The same posting syndicated to several boards is collapsed to one row. See duplicates.
• Expired postings are excluded. Anything past its expires_at is gone.

Results are always newest-first. That isn't configurable — see pagination.

The four matching modes#

Every filter behaves in one of four ways, and knowing which is which explains almost every surprising result:

Text search#

# Rust or Go, no interns — the simple syntax covers most needs.
curl -G https://api.hyperjobs.io/v1/jobs \
  -H "Authorization: Bearer $HYPERJOBS_KEY" \
  --data-urlencode "title=rust OR go -intern"
 
# The same query in boolean form, with a prefix wildcard.
curl -G https://api.hyperjobs.io/v1/jobs \
  -H "Authorization: Bearer $HYPERJOBS_KEY" \
  --data-urlencode "title_advanced=(rust | go) & !intern"

Malformed syntax — an unbalanced quote, a dangling operator — returns 400 {"error": "invalid search syntax", "param": "…", "hint": "…"} rather than matching nothing.

Skills#

Skills are stored as canonical tokens, and the well-known aliases are translated for you on the way in: c++, c#, .net, node.js, react.js, vue.js, and golang all work even though they're stored as cpp, csharp, dotnet, node, react, vue, and go.

Category and level#

Comma means OR — except skill#

Every multi-value filter treats commas as OR — you get a union in one request. (An early draft of this API read commas as AND everywhere, which made a union cost one request per value merged client-side.)

# Software OR Healthcare — the union, in one request.
curl "…/v1/jobs?taxonomies=Software,Healthcare"
 
# Roles in Germany OR the Netherlands, at Director OR Management level.
curl "…/v1/jobs?country=DE,NL&seniority=Director,Management"

The one exception is skill, which is deliberately AND — it expresses required skills, and skill=react,typescript,graphql means all three:

# NOT "Python or AWS". This is "tagged BOTH Python AND AWS".
curl "…/v1/jobs?skill=python,aws"

Different parameters still combine with AND, so country=DE,NL&remote=true is "(Germany OR Netherlands) AND remote". There's no OR across parameters — "remote OR posted this week" is still two requests merged by id.

A bad member inside a comma list — taxonomies=Software,Healthcareee — returns a 400 naming the value, not a quietly smaller result set.

Locations#

curl "…/v1/jobs?country=US"                  # ✓ ISO-2 works now
curl "…/v1/jobs?country=United States,DE"    # ✓ names and codes mix freely
curl "…/v1/jobs?location=United States"      # ✗ — 400, unknown parameter

Salary#

Company#

Every job embeds its company; these parameters filter on that profile. A job whose company hasn't been verified won't match any of them.

# Python roles at big software companies — not the job's country, the employer's.
curl -G https://api.hyperjobs.io/v1/jobs \
  -H "Authorization: Bearer $HYPERJOBS_KEY" \
  --data-urlencode "skill=python" \
  --data-urlencode "company_industry=Software Development" \
  --data-urlencode "employee_count_gte=1000"

Time#

The window measures against the posting date, falling back to the ATS creation date and then to when we first indexed it.

Everything else#

Debugging an empty result set#

Most of the old debugging ritual is obsolete: a misspelled parameter, a bad enum member, or broken search syntax is now a 400 that names the problem, so an unexpectedly empty response almost always means the filters are valid but too tight. Two things to check:

• An accidental AND. skill ANDs its commas, and separate parameters always AND. Drop filters one at a time and watch total — or cheaper, point the same query at /v1/jobs/count.
• A skill token that didn't round-trip. skill is free-text, so skill=Machine Learning returns zero rows without an error — the stored token is machinelearning. See the warning above.