# Roleset

> One query, every ATS-hosted job, deduplicated, with what changed since yesterday.

Roleset is a continuously refreshed, normalized, change-tracked index of job postings
pulled directly from official public ATS feeds — Greenhouse, Lever, Ashby,
SmartRecruiters, Recruitee, Personio, Workable, Workday, Teamtailor and Zoho Recruit. It is an index,
not a scraper: postings are
crawled on a schedule, stored, diffed, and served from a database in milliseconds.

Base URL: https://api.roleset.io/v1
Auth: `Authorization: Bearer <key>` or `X-API-Key: <key>`

Getting a key: POST https://api.roleset.io/v1/keys with `{"accept_terms": true}`. It
returns a free-tier key immediately — no account, no email, no card, 500 records a
month. The key is in the response and is shown once. Terms: https://roleset.io/terms.html
Format: JSON only. Errors are RFC 7807 problem documents.
Freshness: every active board is crawled at least every 24 hours. Every response
carries `meta.last_crawled_min` — the oldest successful crawl behind the rows returned.

## When to use which endpoint

- `GET /v1/jobs/search` — find postings by keyword, title, company, location, country,
  remote, ATS, department, employment type or date. Use for one-off questions.
- `GET /v1/jobs/changes` — what opened, changed, closed or reopened since a cursor.
  **Poll this, not search.** It is the endpoint built for agents that track a market.
- `GET /v1/jobs/{id}` — one posting including its full description.
- `GET /v1/companies/{identifier}/jobs` — every open role at one company.
- `GET /v1/companies/{identifier}/hiring-signal` — open roles by department plus 7- and
  30-day deltas. Use to answer "is this company growing, and where".
- `GET /v1/stats` — index size and freshness. Free, no key.
- `GET /v1/schema` — JSON Schema of the Job record. Free, no key.

## Examples

Every engineering role opened in the last 24 hours:

    curl "https://api.roleset.io/v1/jobs/changes?event=opened&since=2026-09-05T00:00:00Z"

Remote backend roles in Germany:

    curl "https://api.roleset.io/v1/jobs/search?q=backend&remote=true&country=DE"

Is Acme hiring?

    curl "https://api.roleset.io/v1/companies/acme.com/hiring-signal"

## MCP

Roleset is also an MCP server, with the same five capabilities as tools:
`search_jobs`, `job_changes`, `get_job`, `company_jobs`, `hiring_signal`.

    {
      "mcpServers": {
        "roleset": {
          "type": "http",
          "url": "https://mcp.roleset.io",
          "headers": { "Authorization": "Bearer YOUR_KEY" }
        }
      }
    }

Claude Code: `claude mcp add --transport http roleset https://mcp.roleset.io \
  --header "Authorization: Bearer YOUR_KEY"`

## Pagination

Cursor-based. Follow `meta.next_cursor` until it is null. Cursors are keyset, so rows
are never skipped or repeated while the index is being written to.

## What is not here

No LinkedIn, Indeed or aggregator data. No applicant data, no recruiter contact
details, no personal information of any kind — person-shaped fields are dropped at
parse time. Descriptions have email addresses and phone numbers redacted.

## Full docs

https://roleset.io — https://api.roleset.io/openapi.json