API
One REST API for agents: search the job index, track applications on the candidate's own board, and store a tailored CV per job that renders to an ATS-friendly PDF. Everything is scoped to the key's owner.
Authentication
Generate a key at /agents and send it as a bearer token. One key per account; generating a new one revokes the old.
Authorization: Bearer cnk_live_…
Permissions
Every key carries explicit permissions, chosen when it is created. Searching the public job market never implies access to private data.
jobs:read | Search jobs, read job details, list boards and check your quota. Public data only. |
applications:read | See the jobs you track, their status, notes and the CVs attached to them. |
applications:write | Save jobs, move them through your pipeline, add notes and attach CV versions. |
cv:read | Read the CV and parsed profile stored on your career.now account. |
New keys get jobs:read, applications:read and
applications:write; cv:read is opt-in. A missing permission answers
403 with required_scope. Remote MCP clients get the same permissions
through OAuth instead of a key.
Quickstart
Track a job, attach a CV, download the PDF.
curl -s https://career.now/api/v1/applications \
-H "Authorization: Bearer $CAREERNOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://boards.example.com/jobs/123",
"title":"Senior Backend Engineer","company":"Acme"}'
# → {"application":{"id":"01JB…","status":"saved", …}}
curl -s https://career.now/api/v1/applications/01JB…/cv \
-H "Authorization: Bearer $CAREERNOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{"basics":{"name":"Jan Kowalski","email":"[email protected]"},
"work":[{"name":"Acme","position":"Senior Backend Engineer",
"startDate":"2023-01",
"highlights":["Cut p99 latency by 40%"]}]}'
# → {"cv":{"id":"01JC…","version":1,"pdf_url":"/api/v1/cv/01JC….pdf"}}
curl -s https://career.now/api/v1/cv/01JC….pdf \
-H "Authorization: Bearer $CAREERNOW_API_KEY" -o cv.pdf
Jobs
Read-only search over the live index. This is where an agent finds work to track.
GET
/jobs/search
limit: search
needs jobs:read
Search the index with filters and facets.
Query
q |
string | Free-text query. Min 2 chars unless tags is given; max 200. |
tags |
csv | Tags AND-ed into the query. |
remote_type |
csv | remote, hybrid, onsite. |
seniority |
csv | Levels: intern, junior, mid, senior, expert (staff/principal IC), lead, head. e.g. senior,lead. |
bucket |
csv | Job category; each job has exactly one: software (engineers whose posting names no single language), ai-ml, javascript, python, java, dotnet, go, php, ruby, scala, c-cpp (C/C++/Rust), mobile, testing, devops, admin, ux-ui, pm, game, analytics, security, data, support, erp, architecture, management (engineering managers). See facets.buckets for counts. |
product_engineering |
bool | Only product engineering roles: generalist engineers who own product outcomes end to end, where product judgment matters more than one specific language or framework. A flag, so it combines with bucket. |
country |
csv | ISO codes, e.g. US,DE. Matches if ANY copy of a deduplicated job is in that country; each result lists them all in countries. |
remote_from |
string | ISO code of the country the candidate lives in, e.g. PL. Only remote jobs they can take from there: open worldwide, open to a region holding that country (Europe, EMEA, Americas, LATAM, APAC), or remote within it. Stricter than remote_type=remote, which also returns "remote, US only". |
board |
csv | Board keys — see /boards. |
location |
string | Free-text place filter, accent- and exonym-insensitive (Warsaw = Warszawa, Wroclaw = Wrocław). Matches any copy of the job; see locations. |
has_salary |
bool | Only jobs whose published salary contains an actual figure (not "Competitive" or "DOE"). |
salary_from |
int | Annual salary floor: only jobs whose published range reaches at least this amount (top of range). Jobs without a figure never match. |
salary_currency |
string | ISO 4217 currency of salary_from (default USD). Postings in other currencies are compared through a fixed, approximate exchange-rate table; each result keeps its own currency in salary_annual. |
visa_sponsorship |
bool | Only jobs stating visa sponsorship. |
new_since |
datetime | ISO 8601. Only jobs career.now first saw at or after this instant (first_seen_at). Jobs seen before tracking began (2026-09-29) never match. |
sort |
enum | relevant (default when q is given: title matches rank above description mentions), newest (default otherwise), salary (highest annual figure first, compared across currencies via a fixed approximate exchange-rate table; jobs without a figure last). |
page |
int | 1–3. Pagination is capped at 3 pages × 25 results. |
Returns { results[], total, total_is_capped, sort, facets, page, page_size, warnings? }. Each result carries a token, its bucket and product_engineering flag, salary_annual ({min,max,currency} annual figures in the posting's currency, or null), the external apply url, country (the representative copy) and countries/locations (every copy), liveness_status, and quality_score (listing completeness 0-100, not relevance). total stops at 1000. facets = { remoteTypes, seniorities, countries, boards, buckets }, each a list of { value, count } over all matches, plus product_engineering (how many matches are product engineering roles).
- Every
qword must appear (AND). Technology names are normalized: C++, C#, .NET, Node.js/NodeJS/Node JS, Vue.js, Next.js match as whole names, not letter prefixes. - A role named in
q("data engineer", "engineering manager", "frontend", "sre"…) keeps only jobs of compatible role families; level words (junior, senior, staff, principal…) act as a level filter that keeps jobs whose level is not known yet, unlessseniorityis given. relevantranks re-posts by aggregators (e.g. Jobgether) below employers' own postings and, forremote_type=remotewithout a country, jobs open worldwide above region- or country-restricted ones. Useremote_fromwhen you know where the candidate lives.- Check
facetsbefore narrowing further — they show which filter values actually have counts.
GET
/jobs/{token}
limit: job
needs jobs:read
Full detail for one job, including the external apply URL.
Returns The rich job object with description_markdown and a consolidated salary.
- 404 when the token is invalid or the job has aged out of the index.
GET
/boards
limit: boards
needs jobs:read
Every indexed board with its live job count.
Returns { boards: [{ board, count }] }
Applications
The candidate's pipeline — the same board they see at /dashboard/board. Writes here are immediately visible in the UI.
GET
/applications
limit: applications
needs applications:read
List tracked applications, newest first.
Query
status |
enum | Filter: saved, ready (Ready to apply), applied, interview, offer, rejected. |
archived |
enum | false (default: the board, archived cards left out), true (only the archive), all. |
tag |
string | Only applications carrying this tag (case-insensitive). |
Returns { applications: [{ id, url, status, title, company, location, salary_raw, notes, tags, archived, archived_at, created_at, updated_at }] }
POST
/applications
limit: applications
needs applications:write
Track a job.
Body
url required |
string | The job's URL on the original board. |
title |
string | Snapshot, shown on the card. |
company |
string | Snapshot. |
location |
string | Snapshot. |
salary_raw |
string | Snapshot, as printed by the source. |
description |
string | Snapshot, max 20 000 chars. |
job_token |
string | The search token, when the job came from /jobs/search. |
status |
enum | Start somewhere other than saved. |
Returns 201 { application }
- Idempotent on
url: posting the same job again refreshes the snapshot and never resets a status the candidate already advanced. - Send the snapshot fields. Jobs leave the index after ~35 days and the card must still read correctly a year later.
GET
/applications/{id}
limit: applications
needs applications:read
One application with its CV (cv, or null).
Returns { application, cvs[] }
PATCH
/applications/{id}
limit: applications
needs applications:write
Move a card through the pipeline, or annotate it.
Body
status |
enum | saved, ready (Ready to apply — the user approved the CV), applied, interview, offer, rejected. |
notes |
string | Free text, max 5 000 chars. Replaces the existing note. |
archived |
boolean | true hides the card from the board (its status is kept); false restores it to its column. |
tags |
string[] | The user's labels, max 10 of 30 chars. Replaces the existing tags. |
Returns { application }
DELETE
/applications/{id}
limit: applications
needs applications:write
Untrack a job. Its CV goes with it.
Returns { deleted: true }
CVs
A CV belongs to an application, because a tailored CV is tailored to one job. One CV per application: posting again replaces it. The user reviews it from the tracker card and moves the job to ready (Ready to apply) when it is good.
POST
/applications/{id}/cv
limit: cv
needs applications:write
Store the application's CV, replacing the previous one.
Body
(body) required |
CV document | The career.now CV document, sent as the body or wrapped in { "cv": … }. Fields: name (required), headline, contact {email, phone, location, links[]}, summary, achievements[] {title, description}, skills[] {group, core[], items[]} (core prints first, highlighted), experience[] {role, company, start, end, context, summary, bullets[] (string or {text, tag}), stack[], minor}, sections[] {title, entries[] like experience}, education[] {degree, institution, start, end}, languages[] {language, level}. Dates are ISO 8601 (2023-07); no end = current. Strings accept bold, *italic*, code, links. |
Returns 200 { cv: { id, application_id, resume, pdf_url, created_at } } — a new id on every save.
- The template prints dates in one house style and orders roles newest-first, so the agent does not have to.
/skill.mdhas a complete example. - The document is parsed AND rendered before it is stored. Anything that fails returns
422 { error, format }with the exact field, e.g.experience[0].bullets[1].tag must be a string; JSON Resume is refused the same way.
GET
/applications/{id}/cv
limit: cv
needs applications:read
The application's CV.
Returns { cv }
GET
/applications/{id}/cv/download
limit: cv
needs applications:read
A signed link that opens the CV's PDF without a login, for 15 minutes.
Returns { url, expires_at, filename }
- For agents that cannot pass a file to their user (an MCP tool result is text): hand over the
url. It serves the job's current CV, so a re-save inside the window does not break it.
GET
/cv/{id}
limit: cv
needs applications:read
A CV by id.
Returns { cv }
GET
/cv/{id}.pdf
limit: cv_pdf
needs applications:read
The rendered PDF.
Returns application/pdf — a one-column, ATS-friendly A4 document with selectable text.
- Owner-only, like every endpoint here. A CV carries a name, a phone number and an employment history; the only way to open it without a credential is a 15-minute signed link from
/applications/{id}/cv/download. - Rendered on request from the stored document, so template improvements apply to existing CVs. A CV saved in an older format answers
422— save it again.
Feedback
Tell us when data or the API is wrong. Reports are aggregated per source and field and feed the data-quality pipeline.
POST
/feedback
limit: feedback
Report a data or API problem.
Body
category required |
enum | wrong_field, missing_data, dead_link, duplicate, stale, bad_description, search_quality, api_bug, api_suggestion, other. |
message required |
string | What is wrong and how you know, 10-2000 chars. |
job_token |
string | The affected job's token from /jobs/search. |
field |
string | Affected field, e.g. salary, remote_type, posted_at, url. |
observed |
string | The value career.now returned. |
expected |
string | The correct value per the original posting. |
endpoint |
string | For API problems: the endpoint or tool. |
Returns 201 { ok, id }
- Open to every credential. Counted in its own bucket, never against search quota.
Account
The key owner's own data. Reading the CV needs the explicit cv:read permission.
GET
/me
limit: me
needs cv:read
The key owner's CV and parsed profile.
Returns { email, cv_markdown, profile }
GET
/me/quota
unmetered
Remaining quota per endpoint, and the permissions this credential carries.
Returns { plan: "free", window, scopes, auth, quota: [{ endpoint, limit, used, remaining }] }
- Unmetered and open to every credential — safe to call any time to check headroom and permissions.
Freshness
Four fields describe time, and they mean different things.
posted_at | Best available publication date from the source. Usually the real posting date, but on some sources it is a page-modification date, and some sources give none (null). Don't treat it as exact. |
first_seen_at | When career.now first observed this job. Written once, never moved by a refresh. null means the job was first seen before tracking began on 2026-09-29. For a deduplicated job it is the earliest sighting of any copy. Use new_since to ask for jobs that appeared after a moment. |
fetched_at | The most recent crawler refresh (job detail only). Moves every night for a live job, so it says nothing about how new the job is. |
liveness_status | Whether career.now believes the posting is still open (job detail only): null = not checked yet, live = the last check found it open, unknown = the last check was inconclusive, gone = retired. Gone jobs leave the search index, and get_job then answers 404. Jobs also leave the live index about 35 days after publication (archived). |
A full change feed (created, updated, closed, reopened since a moment) is not
offered yet: it needs reliable lifecycle history, which starts with first_seen_at.
For "what's new since yesterday", search with new_since.
Rate limits
Per endpoint, per rolling 24 hours, counted against the key's owner —
not per IP. Every response carries X-RateLimit-Remaining; a
429 carries Retry-After. career.now is free; there is no paid tier.
| Endpoint | Requests / 24h |
search | 50 |
job | 200 |
boards | 30 |
me | 50 |
applications | 500 |
cv | 200 |
cv_pdf | 300 |
feedback | 100 |
For agents
The same reference, plus a workflow and worked queries, is served as an
Agent Skill at /skill.md. MCP clients can use
the same API as tools: remotely at https://career.now/mcp (Streamable HTTP, OAuth) or
locally with npx -y @careernow/mcp (stdio, API key). Setup per client:
/agents.