# Jobs API and MCP > Search open jobs for free with no key, then start and send applications on the person's account. A REST API and an MCP server that signs in only when it has to. Canonical page: https://www.refolk.ai/developers/jobs The talent side of the API: find an open role and apply to it, from your own code or from inside any assistant that speaks MCP. Searching is free and needs no key. Only the calls that act as a person (starting applications, reading them, sending one) need their account, and those sign them in when they are first called. - [Search right now](https://www.refolk.ai/jobs): The same catalog, as a page. Every result links back to it. - [Hiring instead?](https://www.refolk.ai/developers/mcp): The people search, for recruiters and founders. ## The catalog Live postings from thousands of employers, mostly venture-backed companies, read straight off their own job boards every six hours. A posting that closes is retired from search within hours, so a result is a job somebody can still apply to. Salary is shown only where the employer publishes a band. ## Add it to an assistant One URL, no key: **URL** ```text https://www.refolk.ai/api/mcp/jobs ``` **Claude Code** ```text claude mcp add --transport http refolk-jobs https://www.refolk.ai/api/mcp/jobs ``` **JSON config** ```text { "mcpServers": { "refolk-jobs": { "type": "http", "url": "https://www.refolk.ai/api/mcp/jobs" } } } ``` In Claude, ChatGPT or any other chat app that takes a server URL, add it as a custom connector with no authentication. Search works straight away. The first time the person asks to apply to something, the server answers with an OAuth challenge and the app opens a Refolk sign-in in a new window; after that it is connected. > **Why sign-in waits** > > A person looking for work should find out whether there is anything for them > before anybody asks them for an account. So `initialize`, `tools/list` > and both search tools answer without a credential, and only the three tools > that act as the person ask for one. ## The tools | Tool | Account | What it does | | --- | --- | --- | | `refolk_search_jobs` | No | A sentence in, ranked roles out, with how the sentence was read. | | `refolk_get_job` | No | One posting, whole, by id or link. | | `refolk_apply_to_jobs` | Yes | Up to 10 jobs onto the person's list, each with a tailored resume and cover letter written in the background. Sends nothing. | | `refolk_my_applications` | Yes | Where each application stands, or one in full with its cover letter. | | `refolk_send_application` | Yes | Submits one ready application through the employer's own form. Needs `confirmed: true`. | Everything on this side is free. Sending is capped at 25 applications in any seven days, the same limit the app has. ## Search over HTTP **curl** ```bash curl "https://www.refolk.ai/api/v1/jobs/search?query=senior+rust+backend+engineer,+remote+in+Europe" ``` **TypeScript** ```typescript const res = await fetch("https://www.refolk.ai/api/v1/jobs/search", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ query: "product designer in London", limit: 10 }), }); const { jobs, total, nextOffset, interpreted } = await res.json(); ``` **Python** ```python import requests res = requests.post( "https://www.refolk.ai/api/v1/jobs/search", json={"query": "data engineer", "countries": ["DE", "NL"], "remote": True}, ) jobs = res.json()["jobs"] ``` The sentence is read for a role, a level, a place, remote or hybrid, a salary floor and a recency window; whatever is left is ranked as keywords against the title, skills, company and description. `interpreted` says what was read, and any of these fields overrides it: | Field | Meaning | | --- | --- | | `query` | The sentence. `q` works too. | | `remote`, `workplace` | Remote only, or one of `remote`, `hybrid`, `onsite`. | | `countries` | Names, ISO codes or regions (`EU`, `LATAM`). With remote, postings open to anywhere are included. | | `location` | A city or area. | | `seniority` | Any of `intern`, `entry`, `mid`, `senior`, `staff`, `principal`, `manager`, `director`, `executive`. A posting known to be at another level is left out; one with no stated level ranks lower. | | `roleFamily` | One of `engineering`, `data`, `design`, `product`, `sales`, `marketing`, `operations`, `finance`, `people`, `legal`, `support`, `healthcare`, `science`. | | `company` | One employer. | | `minSalary` | Annual floor. A posting with a stated band below it is left out; one that states none stays in. | | `postedWithinDays` | Recency. | | `limit`, `offset` | Up to 50 a page. Pass back `nextOffset`. | `GET /api/v1/jobs/{id}` returns one posting with its whole description. Both endpoints allow any origin, so a page can call them from the browser. Anonymous calls share a rate limit per address; send a key for one of your own. ## Applying over HTTP These need the person's account: an OAuth access token from the sign-in above, or an API key from [the API page](/hire/api). **Start applications** ```text curl -X POST https://www.refolk.ai/api/v1/applications \ -H "Authorization: Bearer $REFOLK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jobs": ["senior-backend-engineer-payments-3f9m2pa"]}' ``` **Check on them** ```text curl https://www.refolk.ai/api/v1/applications?status=ready \ -H "Authorization: Bearer $REFOLK_API_KEY" ``` **Send one** ```text curl -X POST https://www.refolk.ai/api/v1/applications/APPLICATION_ID/send \ -H "Authorization: Bearer $REFOLK_API_KEY" ``` Starting an application never sends anything. It puts the job on the person's list and writes the drafts; they read them at [their applications](/apply/applications), and a send happens only when they press send there or ask for it. A job already on the list comes back in `alreadyQueued` rather than twice. A send that cannot go yet is a `409` `conflict` with a `reason` and a message saying what to do first: `not_ready` while the drafts are being written, `answers_missing` when the form will ask something the person has not answered, `needs_own_browser` for the employers that only accept a submission from the person's own browser (the [extension](/apply/extension) fills those in there), `needs_account` where the form sits behind creating an account on the employer's site. A send that started is a `202`; it runs in the background and its progress shows on `GET /api/v1/applications`. > **Only on the person's say-so** > > A send puts an application in front of an employer in somebody's name and > cannot be taken back. Call it when the person has read the draft and asked for > it, never as a step in a loop. --- ## More of the API documentation - [Quickstart](https://www.refolk.ai/developers/quickstart.md): Create a key, run your first search, and read what comes back. A working request in under two minutes, in curl, TypeScript, and Python. - [Authentication](https://www.refolk.ai/developers/authentication.md): How API keys work: creating one, sending it, rotating it, and what happens when one leaks. Keys are shown once and hashed at rest. - [Credits and limits](https://www.refolk.ai/developers/credits-and-limits.md): What each call costs, what a failed run is charged, what the rate limits are, and how to check a balance before a long run. - [Playground](https://www.refolk.ai/developers/playground.md): Run any endpoint from the browser, signed in, on your own credits. Prefilled examples, the real response, and the equivalent curl for your own code. - [Search in plain English](https://www.refolk.ai/developers/agentic-search.md): POST /v1/search. One sentence in, a ranked shortlist out, with the evidence behind every pick. Blocking or streamed as server-sent events. - [Search with filters](https://www.refolk.ai/developers/structured-search.md): POST /v1/people/search. An exact filter set in, a deterministic page of people out, one flat price a page. Every field, every allowed value, and how to paginate. - [Hiring pipeline](https://www.refolk.ai/developers/pipeline.md): Roles, stages and candidates over HTTP. Open a role, drop a search's people onto it, move them through stages and leave notes. Free. - [Errors](https://www.refolk.ai/developers/errors.md): One error shape for every endpoint, a closed set of types, and which of them are worth retrying. What gets refunded when a call fails. - [MCP server](https://www.refolk.ai/developers/mcp.md): Give Claude, Cursor, VS Code, or any MCP client the ability to search for people mid-conversation. One URL, one header, and your hiring pipeline is reachable too. - [OpenAPI document](https://www.refolk.ai/api/v1/openapi.json): the machine-readable specification. Authenticate with `Authorization: Bearer rfk_live_...`. Keys are created at https://www.refolk.ai/hire/api.