freehire API
Base URL
All endpoints are served under https://freehire.me/api/v1. The API is read-first and open: the job, search, facet, and company endpoints need no authentication and may be called cross-origin.
Authenticated endpoints accept either the browser session cookie (set by sign-in, same-origin) or a personal API key sent as a Bearer token — see the authentication model below. Keys are created in your account, at freehire.me/my/integrations/api-keys, not through this API.
Response envelope
Single items are wrapped as { "data": ... }. Collections add pagination metadata: { "data": [...], "meta": { "total", "limit", "offset" } }. Errors are { "error": "message" } with a matching HTTP status.
{ "data": { "...": "single item" } }
{ "data": [ ... ], "meta": { "total": 4213, "limit": 20, "offset": 0 } }
{ "error": "job not found" }
Pagination
List and search endpoints page with limit (default 20, max 100) and offset (default 0). meta.total reports the total matching the current filters, so you can compute the number of pages.
Pagination is bounded on every list endpoint: offset + limit may not exceed 10000 (pagination too deep → 400). This is deep-paging protection, not a cap on the reported total — use filters to narrow rather than paging that far.
The bound is a refusal rather than a clamp, deliberately: a clamped page would answer 200 carrying rows you did not ask for, and a client walking pages would loop over the same page forever without being able to tell. A 400 means "there is no such page", which is the truth.
Errors
Errors use standard HTTP status codes: 400 (bad request / invalid value), 401 (missing or invalid credentials), 403 (authenticated but not allowed, e.g. a non-moderator), 404 (no such job, company, or owned resource), 429 (request limit exceeded), and 503 (service temporarily unavailable). Application errors use { "error": ... }. nginx rate-limit rejections can return a non-JSON body; see API plans below.
API plans
The public read endpoints answer without a key for personal and non-commercial use. Showing the postings in a product you offer to others needs an API plan, under the data licence.
Send a full-access key as Authorization: Bearer <token>, or use the OAuth access token of a signed-in MCP or CLI connection.
The API plan allows 1,200 requests per 60-second window. The Data plan allows 6,000. Neither paid API plan has a daily request cap. The account shares one budget across its full-access API keys and OAuth connections, including public REST reads and agent search. A browser session cookie does not select the paid API rate.
The limit counts HTTP requests, not returned listings or unique vacancies. A page containing 100 listings costs one request. Re-fetching the same page or vacancy costs another request, including when the data has not changed. There is no separate cooldown for refreshing a vacancy.
Pagination returns 20 listings by default and up to 100 with limit=100. Requests carrying offset or company_slug also pass through separate per-IP nginx limits of 2 requests per second each, including paid requests. The offset limit allows a burst of 50 excess requests; the company_slug limit allows 30. A request carrying both parameters draws on both limits. For sustained pagination or company-filtered reads, keep the combined traffic from one IP within the applicable 2-request-per-second limit.
The gateway returns X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (seconds until reset). A window starts with its first request. Exceeding a request limit returns HTTP 429. Gateway rejections include Retry-After in seconds; nginx rejections can omit these headers and return a non-JSON body. Pause for Retry-After when present; otherwise back off before retrying.
Data freshness and closed jobs
A posting is open until something closes it, and a closed posting carries closed_at and a closed_reason. Nothing is deleted. These are the closers, with the closed_reason each writes:
- The crawl no longer lists the posting:
unseen. A crawl that ran incompletely, or whose board failed, closes nothing. - A source that streams removals reports the posting taken down:
feed_removed. - Two consecutive liveness reads find the page expired, or the source answers that it is gone:
probe_expired. - A source with no close signal at all is closed by age (
expired), and so is a posting whose application deadline has passed. The age rule is a guess, which is why the reason says so. - A board whose crawl has failed for a long time (
board_unreachable,board_gone) or has listed nothing for a long time (feed_empty), or a board that was retired (board_retired). - An aggregator's copy of a posting whose employer's own board freehire already crawls closes in favour of that copy (
ats_covered). - A moderator (
moderated), or the employer on a posting they published themselves (employer_closed).
Postings closed before the reason was recorded carry an empty closed_reason. A closed posting can reopen: when its source lists it again, or a moderator reopens it, closed_at is cleared.
How often a posting is re-checked is set by each source's crawl schedule, and it differs by source; this API does not promise a figure. Search also withholds an open posting its source has not shown for 14 days, but only for sources where a missing listing is evidence: some sources have a longer window of their own, and self-closing, liveness-probed and manually added sources are excluded. An old last_seen_at alone does not prove a posting is out of search. Such a posting stays open and GET /jobs/{slug} serves it.
Closed postings never appear in GET /jobs, in search or in a company's open postings. GET /jobs/{slug} keeps serving them, with closed_at set, so a link you stored still resolves. A company's recent closed postings are at GET /companies/{slug}/closed-jobs.
Keeping a mirror in sync
GET /jobs/changes is the feed of every opening, closing and reopening of a public, canonical posting. To keep a copy of the catalogue current:
- Load the postings you want through the list and search endpoints, and note the time you started.
- Call
GET /jobs/changes?since=<that time>and followmeta.next_cursorascursoruntilmeta.has_moreis false. Store the lastnext_cursor. - From then on, call
GET /jobs/changes?cursor=<stored cursor>on your own schedule. Aclosedchange means delist the posting;openedandreopenedmean fetch it withGET /jobs/{slug}and list it.
The cursor is a position, not a time, so a walk never skips or repeats a change while new ones arrive. Each change carries a seq: for a given public_slug, apply a change only when its seq is greater than the last one you applied, and skip it otherwise. The feed can serve one posting's changes slightly out of order, and the first call with since can repeat a few changes from just before it; this rule makes both harmless. since can reach back 30 days at most, and the feed begins when it was introduced (meta.available_since). A change shows up in the feed shortly after it happens, not at the same instant: the feed trails the oldest transaction still open in the database, so a long-running one delays new entries until it ends. Nothing is lost, only late.
The feed keeps the full history and nothing is deleted from it, so a cursor you hold never expires. Only since is capped, at 30 days back, so a first call stays cheap: a mirror older than that rebuilds from search and then starts the feed with since.
A posting counts as listed while it is open, canonical (not a duplicate of another posting) and public. A posting that stops being listed is a closed change whose closed_reason is the close reason, or duplicate when it became a duplicate of another posting, or private; one that is listed again is reopened.
Change webhooks
Instead of polling the feed you can have it pushed. POST /me/change-webhooks subscribes a URL (with an api or api_data plan); the answer carries the signing secret, once. A subscription can ask for only some companies (company_slugs) and some kinds of change (kinds), and receives changes made from about the time it was created (a change from the moment just before can arrive once; seq dedupes it). It reads the same feed as GET /jobs/changes, in the same order, and the same postings.
A delivery is a POST with a JSON body and these headers:
| Header | Value |
|---|---|
X-Freehire-Timestamp |
Unix seconds when it was signed. |
X-Freehire-Signature |
v1= plus the hex HMAC-SHA256, keyed by your secret, of the timestamp, a ., and the raw body. |
X-Freehire-Delivery |
An id, the same for a retry of the same batch. |
X-Freehire-Event |
job.changes, or webhook.test for a test. |
{"id": "7-4821-90210", "type": "job.changes", "changes": [
{"public_slug": "senior-go-engineer-acme-1a2b", "company_slug": "acme", "seq": 98765, "kind": "closed", "at": "2026-06-20T04:10:00Z", "closed_reason": "unseen"}
]}
changes is a batch of up to 100, oldest first, each shaped like a feed change plus company_slug. Apply a change only when its seq is greater than the last one you applied for that public_slug (this also drops a repeat). opened and reopened mean fetch the posting with GET /jobs/{slug}; closed means delist it.
Verify before you trust a body: recompute the HMAC over the timestamp header, . and the raw body bytes (not re-serialised JSON), compare in constant time, and refuse a timestamp more than 5 minutes from your clock. In Go:
func verify(secret, ts, sig string, body []byte) bool {
n, err := strconv.ParseInt(ts, 10, 64)
if err != nil || math.Abs(time.Since(time.Unix(n, 0)).Seconds()) > 300 {
return false
}
mac := hmac.New(sha256.New, []byte(secret))
fmt.Fprintf(mac, "%s.", ts)
mac.Write(body)
return hmac.Equal([]byte("v1="+hex.EncodeToString(mac.Sum(nil))), []byte(sig))
}
Answer any 2xx to accept a batch. Anything else, a timeout (10 seconds) or a redirect counts as a failure: the same batch is sent again after 30 seconds, doubling up to an hour. Delivery is at least once, so expect repeats and dedupe on seq. After 25 failures in a row, or at once on a 410 Gone, the subscription is disabled (disabled_at and disabled_reason in the list); delete it and create it again to resume, from the changes made then. Plan for the feed instead if you need what happened meanwhile. While your plan has lapsed, deliveries pause and pick up where they stopped once it is renewed.
Authentication model
Browser clients authenticate with an HttpOnly session cookie set on sign-in (same-origin; the SPA cannot read it). Non-browser clients use a personal API key as Authorization: Bearer <token>.
Endpoints marked “Session or API key” accept either; endpoints marked “Session only” (saved searches, subscriptions) accept only the cookie, so a leaked key cannot manage credentials. “Moderator” endpoints additionally require the moderator role.
What is not here
This reference covers every endpoint you can call. A handful are deliberately left out because calling them directly is meaningless: the Gmail and calendar consent redirects (/me/gmail/connect, /me/calendar/connect, and their callbacks), which only a browser can complete; the Telegram bot webhook; the browser-tool websocket relay; the sitemap-cursor helpers behind /sitemap.xml; and the /og/*.png social-preview cards, which render an image rather than answer with JSON.
Managing API keys (POST, GET and DELETE on /me/api-keys) is not documented here, because no API client can call it. Those endpoints accept only the browser session cookie, and additionally require a freshly proven identity — a password re-entry or a sign-in-provider check — that a script has no way to supply. Create and revoke keys in your account instead, at freehire.me/my/integrations/api-keys; the plaintext token is shown exactly once, at creation, so store it then.
The /jobs/{slug}/fit endpoints are pre-rename aliases of /jobs/{slug}/match-analysis and hit the same handlers. They still work, so existing clients do not break — use the match-analysis paths in new code.
Most of this API is also a CLI. If you are writing an agent rather than an integration, freehire covers the same surface with less ceremony — search, tracking, the inbox and CV tailoring — over one API key.
External vs internal endpoints
This reference covers every endpoint a client can call from outside the browser: public reads, and endpoints that also accept a personal API key. Endpoints that require the browser’s own session cookie — saved searches, notifications, moderator tools, the browser extension — are not reachable with a key alone and are documented separately at freehire.me/docs/api/internal.
Filtering jobs
Except where noted below, these parameters apply to GET /jobs/search and GET /jobs/facets. Combine any of them with full-text q.
-
Pass multiple values as a comma-separated list to OR them:
skills=go,rustmatches either. Repeating the param (skills=go&skills=rust) also works. -
Add
<param>_mode=andto require all selected values:skills=go,rust&skills_mode=andmatches both. -
Add
<param>_exclude=<value>to exclude matches:company_type_exclude=outstaffdrops outstaff jobs. -
Different facets are ANDed together; numeric and boolean filters are ANDed too. The geography facets are the one exception — see below.
-
Geography is a single OR group:
regions,countries,metrosandcitieswiden each other instead of narrowing.regions=eu&countries=ITmeans "in Europe or in Italy", so it returns everythingregions=eualone would. To search one country, drop the region:countries=IT. The four name a single concept — where — so picking two places reads as "either", which is what makesregions=eu&countries=BR("Europe or Brazil") useful. There is no AND to switch on:_mode=anddoes not apply to geography. -
Use
regions=noneto match jobs with no resolved geography (an empty region set); it ORs with real region values and supports_excludelike any region. -
A param no filter reads is ignored rather than refused — so old links and saved searches keep working — and comes back in
meta.ignored_params, withdid_you_meanwhen it is only the singular of a real facet. Check it: a dropped filter otherwise looks like a genuinely broad result. At most 10 are listed per response. The same report rides on/jobs/facets,/market/coverageand/companies, which answer{"data": ...}and grow ametablock only when there is something to warn about./companiesfilters on its own vocabulary, so a jobs facet sent there is reported as ignored.
Facets
Every facet below supports repeat-OR, _mode=and, and _exclude as described above.
| Param | Filter | Values |
| --- | --- | --- |
| collections | Collection | yc, techstars, a16z-portfolio, a16z-speedrun, sequoia, accel, greylock, usv, bond, lightspeed, index-ventures, softbank-vision-fund, founders-fund, european, ai, mag7, bigtech, unicorn, fortune500, eastern-roots, indian-roots, ai-native, uk-skilled-worker-sponsor, nl-recognised-sponsor, us-h1b-sponsor, ca-lmia-employer, ie-permit-employer, dk-fast-track-company |
| regions | Region | global, north_america, latam, eu, uk, mena, africa, apac, cis, none |
| work_mode | Work format | remote, hybrid, onsite |
| category | Specialization | software_engineering, backend, frontend, fullstack, mobile, devops, sre, network_engineering, system_administration, telecommunications_engineering, it_support, data_engineering, data_science, data_analytics, ml_ai, ai_engineering, qa, security, hardware, embedded, blockchain, architecture, design, creative, engineering_design, industrial_engineering, occupational_safety, product, project_management, healthcare, skilled_trades, retail, hospitality, logistics, education, personal_services, administration, social_services, science, manufacturing, public_safety, marketing, sales, support, business_analysis, solutions_engineering, developer_relations, technical_writing, recruiting, hr, finance, legal, operations, customer_success, other. The retired value management is still accepted and answered as role_type=people_manager |
| ai_archetype | AI Specialization | rag_app_builder, agent_builder, cloud_ml_platform_engineer, ml_trainer_researcher, fullstack_ai_engineer, devops_infra_engineer |
| seniority | Seniority | intern, junior, middle, senior, lead, staff, principal, c_level |
| role_type | Role type | people_manager — the title names a people-management role. One value only: carrying nothing means no management marker was found, NOT that the posting is individual-contributor work, so role_type_exclude means "no marker", not "IC" |
| skills | Skills | Open vocabulary — call /jobs/facets for live values |
| domains | Industry | fintech, crypto, ecommerce, gambling, gamedev, media, travel, healthcare, edtech, govtech, devtools, cybersecurity, ai, hrtech, adtech, proptech, logistics, mobility, climatetech, other |
| company_type | Company type | product, startup, outsource, outstaff, agency, inhouse, government |
| countries | Countries | Open vocabulary — call /jobs/facets for live values |
| cities | City | Open vocabulary — call /jobs/facets for live values. Recognized dictionary aliases such as München and Köln resolve to their canonical city names. |
| metros | Metro area | Open vocabulary — call /jobs/facets for live values |
| relocation | Relocation | not_supported, supported, required |
| employment_type | Employment | full_time, part_time, contract, internship, fellowship |
| engagement | Contract terms | ir35_outside, ir35_inside, w2, 1099, c2c, contract_to_hire, b2b, uop, umowa_zlecenie, umowa_o_dzielo, clt, pj, tk, gph, samozanyaty, ip, freiberuflich, arbeitnehmerueberlassung, zzp, auto_entrepreneur, portage_salarial, autonomo, monotributo — employee or own business, in each market's own term (UK IR35, US W-2/1099/C2C, Polish B2B and umowy, Brazilian CLT/PJ, Russian ТК/ГПХ/самозанятость/ИП, German, Dutch, French, Spanish and Argentine freelance statuses), as the title, the description or a source's own contract-type field states it; a posting offering several carries each, one that does not say carries none. Separate from employment_type |
| english_level | English | none, a1, a2, b1, b2, c1, c2, native |
| posting_language | Job language | Open vocabulary — call /jobs/facets for live values |
| reality | Posting reality | fresh, stale, likely-evergreen |
| salary_currency | Currency | USD, EUR, GBP, RUB |
| perks | Perks mentioned | generous_pto, four_day_week, 401k_match, parental_leave, retirement_plan, tuition_reimbursement, unlimited_pto, health_insurance, mental_health, learning_budget, home_office_stipend, sabbatical, sign_on_bonus — matched from the description; a posting without one does not mention it, which is not the same as not offering it |
| equity | Equity | salary_and_equity, equity_only, not_stated — not_stated means none was read, not that the job offers no equity |
| company_slug | Company | Open vocabulary — call /jobs/facets for live values |
| source_type | Source type | ats, company, aggregator, social |
| clearance_levels | Clearance level | none, confidential, secret, top_secret, ts_sci, public_trust, interim, other. none = no detected clearance requirement (the same postings as requires_clearance=false); other = a non-US scheme (UK SC/DV, AU NV1, NATO) or a clearance stated with no level; interim is stated beside a level, not instead of one |
| source | Source | Open vocabulary — call /jobs/facets for live values |
| company_size | Company size | 1-10, 11-50, 51-200, 201-500, 501-1000, 1000+ |
| education_level | Education level | none, bachelor, master, phd |
| salary_period | Salary period | year, month, day, hour |
| is_tech | Technical role | tech, non_tech |
Numeric & boolean filters
| Param | Filter | Values |
| --- | --- | --- |
| visa_sponsorship | Visa sponsorship | true, false |
| requires_clearance | Security clearance required | true, false |
| via_recruiter | Posting says a recruiter publishes it for a client | true — the description says so; false — every posting not marked, including recruiter posts that never say so |
| former_employers | Hiring again: companies you have worked at and left | true — signed in only, read from your experience bank; a name that does not resolve to exactly one company is left out. Anonymous, it is reported in meta.ignored_params. /jobs/facets never applies this filter, so its counts ignore it even for signed-in callers |
| watchlist | Your watchlist: companies you follow | true — signed in only; an empty watchlist matches nothing. Anonymous, it is reported in meta.ignored_params. Kept in a saved search, so watchlist=true is the alert for new postings at the companies you follow. /jobs/facets never applies this filter, so its counts ignore it |
| salary_min | Minimum salary | integer — jobs whose minimum salary is at least this (pair with salary_currency) |
| salary_max | Maximum salary | integer — jobs whose maximum salary is at most this (pair with salary_currency) |
| experience_years_min | Minimum experience | integer — jobs requiring at least this many years |
| experience_years_max | Maximum experience | integer — jobs requiring at most this many years, the same figure experience_years_min bounds from below. Use 0 for jobs stating no prior experience is required. Either bound excludes jobs that state no requirement at all, unless experience_include_unspecified is set |
| experience_include_unspecified | Include unstated experience | true — with either experience bound, also keep the jobs that state no experience requirement (most of the catalogue). Has no effect without a bound |
| experience_only_seniority_unspecified | Experience only without a level | true — apply either experience bound only to the jobs that carry no seniority level; a job with a level passes the bound whatever it states. With seniority and seniority_include_unspecified this reads "one of these levels, or no level and within the bound". Has no effect without a bound |
| seniority_include_unspecified | Include unstated seniority | true — with seniority, also keep the jobs that carry no seniority level (most of the catalogue). Has no effect without an included seniority |
| posted_within_days | Posted within | integer — jobs whose SOURCE states a posting date in the last N days. Some boards restate that date on every crawl, so a job open for months can satisfy a narrow bound here; open_within_days is the one that cannot be rewritten from outside |
| open_within_days | Open within | integer — jobs first recorded by freehire in the last N days, i.e. how long the posting has been in the catalogue regardless of the date its source states. Independent of posted_within_days; both may be set and they narrow together |
| apply_questions_max | Application questions | integer ≥ 0 — jobs whose application form requires at most N questions beyond name, contact details and CV (3 = the "short form" filter). Jobs with no form freehire could read are excluded: unknown is not short |
| auto_apply_available | Auto-apply can attempt it | true — only postings whose ATS freehire auto-apply can currently attempt to fill and submit for; a provider-eligibility signal, never a guarantee the submission succeeds |
| work_mode_remote_anywhere | Remote from anywhere, other modes at home | true — with remote and a physical work_mode both selected and a geography facet set, reads "remote anywhere, OR hybrid/onsite within the geography" instead of ANDing them. Otherwise, or with work_mode_mode=and, it changes nothing |
| work_mode_remote_regions | Remote arm: regions | Region values, as regions — bound the remote arm of work_mode_remote_anywhere. Read only while it is in force |
| work_mode_remote_countries | Remote arm: countries | ISO 3166-1 alpha-2 codes, as countries — bound the remote arm of work_mode_remote_anywhere, ORed with work_mode_remote_regions. Read only while it is in force |
Recipes
-
Senior Go, remote, in the CIS region —
q=go&seniority=senior&work_mode=remote®ions=cis -
Backend roles, freshest first, in Germany —
category=backend&countries=DE&sort=posted_at&order=desc -
One country only — no region param, or it widens back out —
countries=IT&employment_type=contract -
Must use both Go and Rust —
skills=go,rust&skills_mode=and -
Exclude outstaff companies —
company_type_exclude=outstaff -
At least $100k, with visa sponsorship —
salary_currency=USD&salary_min=100000&visa_sponsorship=true -
Excluding jobs that need a security clearance —
clearance_levels=none -
Jobs stating Secret or Top Secret clearance —
clearance_levels=secret,top_secret -
Only jobs that need a security clearance —
requires_clearance=true