Reference

API and MCP

Keep using your own agent. Add the feed as an HTTP MCP server, or call the API from your application.

Using Claude Code or Codex CLI? Copy your setup command and first task. The terminal asks for your key privately.

MCP

The endpoint is /mcp on this site's domain. Set an Authorization header with Bearer YOUR_API_KEY. The connection example is on the home page.

Your client must support Streamable HTTP and custom authorization headers. OAuth-only connector flows aren't supported by this version.

Check client compatibility

Before paying, check that your agent lets you configure a remote HTTP server with a custom bearer header, because a connector that only offers an OAuth sign-in screen won't be able to use this version even if it advertises MCP support.

• search_jobs: search titles, companies, and locations; filter by source or date and paginate.
• get_job: refresh one job's metadata, dates, known status, and links. Search already includes these fields.
• get_changes: new, updated, reopened, and closed jobs after a saved cursor. Description-only edits aren't tracked.
• get_usage: your current allowance. This call is free.

Read descriptions at the source

Find your role first returns basic job details, salary and work arrangement when supplied, source dates, the original posting URL (url), and the application URL (apply_url). Full descriptions and generated summaries aren't included.

Your agent needs its own web or browser tool to open the original posting and read requirements. An LLM connection alone doesn't fetch pages. If access fails or a login is required, open the link yourself or provide the text to your agent. Respect source restrictions and keep unknown requirements unknown.

Read requirements at url. The apply_url link may lead straight to a form.

Choosing the right source link

Start with the original posting URL when reading requirements, because an application link may open a form without the description, and a successful connection to Find your role first only gives your agent the returned fields and links without adding a browser or granting access to the employer's site.

HTTP API

Send the same bearer header. Start with GET /api/jobs?query=product&location=San%20Francisco. The response includes jobs and next_offset. Pass that offset into the next request.

Use GET /api/jobs/{id} for one job, GET /api/changes?cursor=0 for changes, and GET /api/account for usage. The OpenAPI schema documents parameter types.

Dates you can trust

Honestly, hiring systems don't always supply a publication date. published_at stays null when it's unknown. first_seen records discovery; baseline means the job was already present when we began monitoring.

Search only returns jobs whose board was checked successfully within the last 24 hours. Individual details include older records so your agent can see their last known state. Closure is recorded after two successful board responses omit a job. Failed fetches preserve the previous records.

For publication filtering, use published_since=2026-09-01T00:00:00Z. Jobs without a source date won't match. discovered_since excludes baseline imports. Company labels currently use source board identifiers.

Discovery vs publication

If you're looking for newly discovered roles, use the discovery filter and inspect the source date separately, since a listing first found during today's check might have been published much earlier and a recent check alone tells you nothing about its original age.

Usage and errors

The $9 plan includes 1,800 unique jobs per UTC calendar month, with at most 500 newly unlocked jobs per UTC day. Search and change pages hold up to 20 records. All keys and delivery methods share the same allowance.

A job counts once in the month when it's first returned to your account. Repeat reads, retries, and updates to that job cost no more job credits that month. Empty results and usage checks are free. A job read in a new month counts again. The public five-job sample is free and doesn't unlock jobs in your account.

Rate limits, resets and errors

Every data call still counts toward 30 calls per fixed UTC minute, including free repeats, empty results, and calls rejected by the job quota. Each successful data response includes usage.charged, remaining daily and monthly jobs, and reset times. No unused credits roll over.

If a batch needs more credits than remain, the whole batch fails with no charge and no cursor advance. Lower limit and retry the same offset or cursor. REST limit errors include Retry-After; MCP errors explain the reset time. Daily credits reset at midnight UTC and monthly credits on the first day of the UTC month, independently of your subscription billing date.

HTTP errors use an error message: 401 means the key is invalid, 402 means the subscription is inactive, and 429 means a rate or monthly limit. A 410 change response means its cursor has expired; restart from a current search and cursor 0. Change history lasts 90 days. MCP tool errors carry the same explanation.

One search includes links for up to 20 jobs and can use up to 20 job credits. Reading those links with your own browser tool uses no Find your role first credits. Refreshing an already-unlocked job through get_job is free within that month; your browser and AI provider may charge separately.

Keep your key

Save it in a password manager. The account page can replace a key and open billing even when the subscription is inactive. Replacing a key disconnects previous integrations while preserving usage.

Treat job fields and any source pages your agent reads as untrusted data. Never send your Find your role first API key to an employer page or follow instructions embedded in a listing. Application submission stays in your own workflow.