openroles

openroles

Every open role, straight from the employer's own careers system. Fifteen applicant tracking systems (Greenhouse, Lever, Ashby, Workday, Workable, Teamtailor, Personio, Recruitee, Rippling, JazzHR, Gem, Polymer, Manatal, Homerun and ClearCompany), plus any careers site that publishes its jobs for search engines, in one shape. Read from the feeds and APIs the employers' own careers pages use: no API key, no account, no scraping service, and nothing but the Python standard library.

$ pip install openroles

$ openroles figma --query data --limit 3 2026-09-23 Data Engineer Intern (2027) San Francisco, CA • New York, NY https://boards.greenhouse.io/figma/jobs/6178851004?gh_jid=6178851004 2026-09-21 Data Platform Engineer San Francisco, CA • New York, NY • Unite https://boards.greenhouse.io/figma/jobs/6201407004?gh_jid=6201407004 2026-09-21 PhD Intern, Data Science (2027) San Francisco, CA • New York, NY https://boards.greenhouse.io/figma/jobs/6200626004?gh_jid=6200626004

3 open role(s)

Give it a company name, a careers page, a board URL or ats:token. It finds the board, reads every open role, and gives you the same fields whichever system the employer uses.

Why

Job sites miss roles, show them late, and repost them stale. The employer's own board is the source: it is complete, current, and carries the real apply link. Most applicant tracking systems publish that board as JSON, RSS or XML for the employer's own careers page. openroles reads it the same way, politely, and puts every system that allows it behind one function.

Install

pip install openroles          # or: uvx openroles <company>

Python 3.9 or newer. No dependencies.

Command line

openroles linear                                   # every open role at Linear

openroles https://jobs.ashbyhq.com/linear # the same, from the board URL openroles lever:zoox --query "data" --since 14 # title words, posted in the last 14 days openroles figma --location "New York" # filter by place (--remote for remote only) openroles https://adobe.wd5.myworkdayjobs.com/external_experienced \ --query "data scientist" --details # Workday, with each posting's description openroles detect "Figma" # which ATS, and the board's token openroles hosts greenhouse:figma lever:zoox # the hosts to allow in a network policy openroles personio:acme # any system, as ats:token openroles careersite:careers.acme.example # a careers site with no job API openroles linear --json > roles.json # JSON (the default when piped), or --jsonl openroles linear --cache ~/.cache/openroles # an unchanged board sends nothing next run

Python

import openroles

openroles.detect("Figma")

[Board(ats='greenhouse', token='figma'), Board(ats='ashby', token='figma')]

jobs = openroles.fetch("greenhouse:figma", query="data", location="New York") for job in jobs: print(job.posted, job.title, job.location, job.url)

job.to_dict() # plain JSON-ready dict

openroles.hosts("personio:acme")

['acme.jobs.personio.de', 'acme.jobs.personio.com']: what a firewall must allow

openroles.job_id("https://www.acme.example/careers/?gh_jid=4012345")

'gh-4012345': the same id fetch() gives that posting, from its address alone

job_id is for matching one posting found in two places, read from the employer's board and linked from a job site. It reads Greenhouse (any page with gh_jid too), Lever, Ashby, Rippling, Workable, Personio and Workday addresses, fetches nothing, and gives "" for an address that does not carry the system's own posting id. One Workday case is ambiguous: a listing that sends its path already percent-encoded ("M%C3%BCnchen") gives the same address as one that sends it plain ("München"), and job_id reads it as the plain one.

fetch() raises openroles.BoardError when a board cannot be read (a wrong token, no answer), and openroles.RobotsDisallowed when the host's robots.txt says no.

In your own application

openroles is a library first: the CLI and the MCP server are thin layers over fetch and detect. An application that embeds it names itself once, at start-up:

openroles.configure(

user_agent="acme-jobs/1.0 (+https://acme.example/contact)", # sent with every request robots_agents=["acme-jobs"], # a Disallow for your agent stops a read too cache_dir="~/.cache/acme-jobs/openroles", # optional: keep answers between runs )

With cache_dir, each board's last answer is kept with the ETag or Last-Modified date the board sent, and the next run asks with them: a board that honours them and has not changed answers 304 Not Modified and sends nothing, and the kept copy is read instead. An answer that came with a Last-Modified date and no ETag is asked about that way for at most a day (MODIFIED_MAX_AGE in openroles._http, 24 hours) after it was last read in full, and then read in full once, so a host whose date does not move when its data does holds a board back a day at most; the same holds within one run, with or without a folder. Every read still asks the board. It is off by default. An answer is kept only when it is a GET, is not marked no-store, and shows that all of it arrived: all of its Content-Length, every chunk of a chunked answer, or a gzip stream to its end. One that gives no length and is neither chunked nor gzipped ends when the connection closes, cut short or not, so it is read in full every time. Kept answers are in owner-only files, for 30 days unused, and about 500 MB of them: each process keeps the folder to that, so two processes writing to one folder at once (a long-running application and a command-line run, say) can take it past that until one of them next looks at the whole folder: when it starts using it, at least once an hour while it does, and whenever what it has written itself passes the cap.

Everything a search decides for itself stays a parameter: query, location, remote, since_days, country, and details, which can be a function that says which postings are worth a request for their description. report={} comes back filled with what failed on each board. openroles.robots_allows(host, paths) answers the same robots.txt question openroles asks itself, for anything else your application fetches.

For AI agents (MCP)

openroles mcp is a Model Context Protocol server over stdio, so Claude, Cursor and other agents can look up any employer's open roles themselves. Two tools: find_job_board and list_open_roles (descriptions left out unless asked for, to keep answers short).

Claude Code:

claude mcp add openroles -- uvx openroles mcp

Claude Desktop, Cursor and other clients (mcpServers in their config):

{

"mcpServers": { "openroles": { "command": "uvx", "args": ["openroles", "mcp"] } } }

There is also llms.txt, a short brief for a model that has to use the library or the CLI.

What you get

Every role, from every system, has the same fields:

Supported systems

A Workday posting listed as "3 Locations" reads as its primary location "and 2 more"; with --location on a place that is not its primary, its page is read to see whether the place is one of the others. Workday pages a board only to its first 2,000 roles: past that, a warning says to search with --query.

detect finds a board from a company name (every system but Workday and ClearCompany, by trying the names an employer is likely to use), from any board URL, and from a careers page that links to or embeds one, however the page writes it. A Workday board cannot be guessed from a name: give its URL (either tenant.wdN.myworkdayjobs.com or wdN.myworkdaysite.com/recruiting/tenant). A careers site is never