Skip to content
Search jobs inside your AI agent. Claude, ChatGPT, Claude Code, Codex, Gemini, Cursor and Grok
Connect
v1.0.0
OpenAPI 3.1.0

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:

  1. Load the postings you want through the list and search endpoints, and note the time you started.
  2. Call GET /jobs/changes?since=<that time> and follow meta.next_cursor as cursor until meta.has_more is false. Store the last next_cursor.
  3. From then on, call GET /jobs/changes?cursor=<stored cursor> on your own schedule. A closed change means delist the posting; opened and reopened mean fetch it with GET /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,rust matches either. Repeating the param (skills=go&skills=rust) also works.

  • Add <param>_mode=and to require all selected values: skills=go,rust&skills_mode=and matches both.

  • Add <param>_exclude=<value> to exclude matches: company_type_exclude=outstaff drops 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, metros and cities widen each other instead of narrowing. regions=eu&countries=IT means "in Europe or in Italy", so it returns everything regions=eu alone 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 makes regions=eu&countries=BR ("Europe or Brazil") useful. There is no AND to switch on: _mode=and does not apply to geography.

  • Use regions=none to match jobs with no resolved geography (an empty region set); it ORs with real region values and supports _exclude like 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, with did_you_mean when 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/coverage and /companies, which answer {"data": ...} and grow a meta block only when there is something to warn about. /companies filters 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&regions=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

Server:https://freehire.me/api/v1

Production

Client Libraries

Onboarding

​
Onboarding Operations

/onboarding/matches

​

Open postings ranked by how well their skills match a caller-supplied skill list, under the jobs-search filters in query. Public: it is what the CV-first onboarding shows a visitor who has no account and so no stored profile. Answers the top ten.

Body·

required
application/json

What the onboarding searches with: the CV's skills and the answers as a jobs-search query.

  • Canonical skill tags, at most 50. They rank the answer; they do not filter it.

  • A /jobs/search query string (work_mode=remote&posted_within_days=7, ...). An unknown param is named in meta.ignored_params.

Responses

  • application/json
  • application/json
Request Example for post/onboarding/matches
curl https://freehire.me/api/v1/onboarding/matches \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "skills": [
    "go",
    "kubernetes",
    "postgresql"
  ],
  "query": "work_mode=remote&category=backend&posted_within_days=7"
}'
{
  "data": [
    {
      "job": null,
      "match_percent": 1
    }
  ],
  "meta": {
    "total": 1,
    "limit": 1,
    "offset": 1,
    "ignored_params": [
      {
        "param": "string",
        "did_you_mean": "string"
      }
    ],
    "ignored_values": {
      "additionalProperty": [
        "string"
      ]
    },
    "total_is_lower_bound": true
  }
}

Jobs (Collapsed)

​

Public, unauthenticated reads. Jobs are returned in one wire shape (addressed by public_slug, never an internal id) shared by the list, detail, company, and search responses. Closed postings are excluded from lists and search and served only by the detail endpoint.

Fit (Collapsed)

​

Personalized signals computed against the caller’s profile or stored CV. All accept the session cookie or an API key. The skill-match endpoint is deterministic (no LLM); the match-analysis endpoints run the LLM chain and draw on your daily allowance. All take the same facet filter params as search where they narrow a market or candidate set.

Companies (Collapsed)

​

Search (Collapsed)

​

Full-text job search with the shared filter vocabulary, facet counts, similar jobs and the reference data behind search.

Company feedback (Collapsed)

​

Signed-in users leave a 1–5 star rating plus category and text about a company, shown under their site-wide pseudonymous persona (never a user id). Reads are public; writes are cookie-only. A reader can report a specific review, and a moderator can hide it.

Company feedback Operations

Auth (Collapsed)

​

Register/login set the session cookie and return the user. Logout clears it. me resolves the caller (cookie or API key). OAuth sign-in is a redirect flow.

Assistant (Collapsed)

​

The same agent the web app and browser extension chat with, over HTTP: create a conversation, then post messages to it. All routes accept the session cookie or an API key (autopilot is cookie-only — see below) and act on a session you own; someone else’s session id answers 404, same as one that never existed. Turns run one at a time per session — a message sent while one is already running queues rather than running alongside it. preset selects which conversation this is: chat (default), profile (the experience interviewer), browse (a browsing session held from the extension’s side panel), interview (a mock-interview rehearsal), debrief (after a real one) or apply (the conversation about one automatic application) — the last three must name the vacancy via ?job=<slug>, an application you already hold. An application holds one apply conversation: asking again returns it with 200 instead of creating a second. A tailor session cannot be created here; it is minted by the CV tailoring bootstrap, which knows the CV and vacancy to bind it to.

Submissions (Collapsed)

​

Any signed-in user can submit a vacancy for moderation and read their own queue. The review actions are moderator-only; approval mints a live job.

Reports (Collapsed)

​

Any signed-in user can flag a problem with a live vacancy. Review actions are moderator-only; resolving may soft-close the reported job.

Reports Operations

Feedback (Collapsed)

​

Votes on jobs and companies, and ghost reports: one person states they applied to a posting and were never answered, feeding the ghost-signal evidence used elsewhere in the API (see the reality field on a job). Nothing here reaches a moderator and nothing here closes the job directly.

Résumé (Collapsed)

​

Your career profile and stored CV, session-only (a browser feature, like saved searches). The profile is a singleton keyed by your session — no id in the path. The verdict and ATS report are read-only sub-resources computed from the profile and CV; résumé storage degrades to 501 when object storage is unconfigured.

Résumé Operations

Account (Collapsed)

​

Stats (Collapsed)

​

Aggregate market intelligence, all public and all unauthenticated. Every figure is served from a precomputed rollup rather than counted live, and nothing here exposes a record-level field or a user identifier — these are counts over the catalogue, not a way to read it.

Contributions (Collapsed)

​

Turning a URL in the wild into something freehire knows about. One intake sequence serves every surface — the website, the bot, the extension and the CLI — deliberately, so a pasted link gets the same answer everywhere.

Community (Collapsed)

​

The lighter per-user surfaces: a vote on a job or company, the account-level notification rule (gates the saved-job apply reminder and both lifecycle nudges), and the public discussion threads. Votes and notification settings take a key; posting to a thread is browser-owned.

Referrals (Collapsed)

​

Two sides of the same marketplace: an employee offers to refer into the company they work at (proof required, moderated), and a candidate asks one of that company's approved referrers for an intro. A candidate never sees who the referrer is, and a referrer sees the candidate's CV only through a short-lived view. Moderation of offers is moderator-gated.

Talent Network (Collapsed)

​

A public, anonymised catalogue of candidates who opted into being found. Membership is a single toggle on users, distinct from user_profiles; a member is addressed by a minted handle, never by their account id or username. Every string a public response carries is a value a dictionary resolved, a number or a date — never text copied from a CV — so no name, employer, institution or free-text field appears anywhere in it.

CV (Collapsed)

​

Your CVs, and the tailoring flow that reframes one toward a single vacancy. Authoring is browser-owned — create, update and delete are session-only — while reading a CV, patching it, and rendering the PDF also accept an API key, because that is the half a tailoring agent drives. Every CV is owner-scoped: an id you do not own is a 404, not a 403.

Experience (Collapsed)

​

The durable record a CV is built from: employments, and the evidence atoms under them. Every atom carries who asserted it — you, or a model that inferred it — and only your own assertions may be written into a CV. Reading accepts an API key; editing is session-only.

Mail (Collapsed)

​

Your job mail, and the link between a message and the application it belongs to. Mail arrives three ways: a connected Gmail account, the hosted freehire address, or a batch your own client pushed. Only the first two are classified by freehire — pushed mail is yours to triage, which is what makes that tier free. Everything here takes a full-scope API key, so a harness can drive the whole surface; the Gmail consent redirect is the one exception and stays browser-only.

Answer bank (Collapsed)

​

Auto-apply (Collapsed)

​

Autofill (Collapsed)

​
Autofill Operations

DirectApply (Collapsed)

​
DirectApply Operations

Email preferences (Collapsed)

​

Plan (Collapsed)

​

Plans (Collapsed)

​
Plans Operations

Catalogue export (Collapsed)

​

Full-catalogue files for the Data plan (api_data). A snapshot is one gzip file, jobs.jsonl.gz: UTF-8 JSON Lines, one job per line, each in the same wire shape as GET /jobs/{slug} (full description included), covering the open, canonical, public postings the search index lists. The file is streamed, so it is not one JSON document; read it line by line. Every snapshot has a schema_version, a row count, a byte size and a SHA-256 to verify the download. Snapshots are named by UTC day and the last few are kept. How often a new one appears is set by the operator timer, not by this API: read date and generated_at rather than assuming a schedule. To stay current between snapshots, re-fetch single jobs with GET /jobs/{slug}. The licence is the API plan's: show the data in your own product, do not resell it as a dataset or feed, and stop showing it when the plan ends — see /terms#data-licence.

Catalogue export Operations

Change webhooks (Collapsed)

​

Push delivery of the change feed to your own endpoint. Session or API key; needs an api or api_data plan. See Change webhooks above for the payload and how to verify a signature.

Speech (Collapsed)

​

Models