# roles.watch API (v1)

On the paid plan: the companies you watch, their open roles, and when we last read each careers page, as JSON. With a personal key you create in your account. It reads the same facts as the [company pages](https://roles.watch/companies), for your own list only, and nothing about anyone else. A read + write key can also add, remove and snooze companies on your list.

Web version: https://roles.watch/developers

## Try it

[Sign in](https://roles.watch/signin), open the account menu, choose API keys, and create a key. It starts with `rw_` and is shown once, so copy it then. Then paste this into a terminal, with your key in place of `rw_YOUR_KEY`:

```bash
curl -H "Authorization: Bearer rw_YOUR_KEY" \
  https://roles.watch/api/public/v1/companies/anthropic
```

No company is listed right now, so there is no live answer to show here.

That is live data, cached for up to two hours. The API doesn’t send alerts; the email does that.

## Keys and your list

- API and MCP are included with the paid plan.
- Send your key on every call as `Authorization: Bearer rw_…`. Without one, a company or the MCP server answers 401.
- If your account isn’t on the paid plan, a key answers 403 `paid_plan_required`. A downgrade suspends your keys without deleting them, and they work again when you upgrade.
- A key reads only the companies you watch. Any other company answers 403.
- You can have 3 keys at a time. Create and revoke them under API keys in your account menu. We store only a hash, so a lost key can’t be shown again: revoke it and make another.
- Keep keys out of code you share. Anyone with your key can read your list.

## List companies

```
GET /api/public/v1/companies
```

With your key: the companies you watch that we read in the last 48 hours with open roles, a page at a time, sorted by `slug`. When there are more, `next_page_token` is set: send it back as `page_token`, with the same `q`, and repeat until it is null. The token is opaque; don’t parse it or build one.

| Parameter | In | Type | Meaning |
| --- | --- | --- | --- |
| `q` | query | string | Optional. Only companies whose name, slug or website contains it, ignoring case. Up to 60 characters. |
| `page_size` | query | integer | Optional. Companies per page, 1 to 100. Default 50. |
| `page_token` | query | string | Optional. A `next_page_token` from the previous page. Send the same `q` with it. |

```bash
curl -H "Authorization: Bearer rw_YOUR_KEY" \
  "https://roles.watch/api/public/v1/companies?page_size=3"
```

Response:

| Field | Type | Meaning | Null when |
| --- | --- | --- | --- |
| `companies` | array of CompanySummary | This page of companies, sorted by `slug`. At most `page_size`. | Never |
| `next_page_token` | string | Pass it as `page_token`, with the same `q`, for the next page. Opaque: don’t parse or build it. | This is the last page. |
| `total_size` | integer | Companies you watch that match `q` (or all of them), across every page. | Never |

Each item in `companies` (CompanySummary):

| Field | Type | Meaning | Null when |
| --- | --- | --- | --- |
| `name` | string | The company name. | Never |
| `slug` | string | Its id in our URLs. Stable while the name is. | Never |
| `page_url` | string (URL) | Its public page on roles.watch. | Never |
| `api_url` | string (URL) | Its entry in this API (v1). | Never |
| `website` | string | Its website as we store it: usually a bare domain like `stripe.com`, sometimes a URL. | We don’t know it. |
| `checked_at` | string (ISO 8601 time) | When we last read its careers page, RFC 3339 in UTC. Always within the last 48 hours. | Never |
| `open_roles` | integer | Roles listed on its careers page at that read. Always at least 1. | Never |
| `snoozed` | boolean | You snoozed it: its roles stay out of your email and your New list until the snooze ends. We keep reading its careers page. Set with `POST {slug}/snooze`, clear with `DELETE {slug}/snooze`. | Never |
| `snoozed_until` | string (ISO 8601 time) | When the snooze ends, RFC 3339 in UTC: midnight at the start of that day in your time zone. | Not snoozed, or snoozed until you turn it back on (`snoozed` says which). |

Without a key, the list is every company we read, names and links only: no roles and no counts. It is how you find a `slug` before you add a company.

```bash
curl "https://roles.watch/api/public/v1/companies?q=ramp"
```

Response without a key:

| Field | Type | Meaning | Null when |
| --- | --- | --- | --- |
| `companies` | array of CompanyLink | This page of companies, sorted by `slug`. At most `page_size`. | Never |
| `next_page_token` | string | Pass it as `page_token`, with the same `q`, for the next page. Opaque: don’t parse or build it. | This is the last page. |
| `total_size` | integer | Companies we list that match `q` (or all of them), across every page. | Never |

Each item in `companies` without a key (CompanyLink):

| Field | Type | Meaning | Null when |
| --- | --- | --- | --- |
| `name` | string | The company name. | Never |
| `slug` | string | Its id in our URLs. Stable while the name is. | Never |
| `page_url` | string (URL) | Its public page on roles.watch. | Never |

## Get one company

```
GET /api/public/v1/companies/{slug}
```

| Parameter | In | Type | Meaning |
| --- | --- | --- | --- |
| `slug` | path | string | A `slug` from the list. Another spelling, the company’s domain or its old id answers 308 to the canonical URL. |
| `title` | query | string | Optional. Only roles whose title contains it, ignoring case. Up to 60 characters. |
| `page_size` | query | integer | Optional. Roles per page, 1 to 100. Default 10. |
| `page_token` | query | string | Optional. A `next_page_token` from the previous page of this company. Send the same `title` with it. |

```bash
curl -H "Authorization: Bearer rw_YOUR_KEY" \
  https://roles.watch/api/public/v1/companies/openai
```

`first_read_at` is when roles.watch first saw a role, always set. `first_seen_at` is when it opened, as near as we know: the read that first found it on a board we were already reading. It is null for a role that was already open at our first read of the board, because we don’t know when it opened. `opened_last_7_days` and `first_seen_at` are also null when we haven’t read the board long enough, or without gaps, to back a number. We would rather say nothing than guess.

The 10 newest open roles come back by default. Send `title` for roles whose title contains it (any case); `matching_roles` counts them across pages. For more, send `page_size` (up to 100) and follow `next_page_token` as `page_token`, with the same `title`, until it is null.

```bash
curl -H "Authorization: Bearer rw_YOUR_KEY" \
  "https://roles.watch/api/public/v1/companies/openai?title=engineer&page_size=50"
```

Roles are newest first; each page is that order continued.

Response (Company):

| Field | Type | Meaning | Null when |
| --- | --- | --- | --- |
| `name` | string | The company name. | Never |
| `slug` | string | Its id in our URLs. Stable while the name is. | Never |
| `page_url` | string (URL) | Its public page on roles.watch. | Never |
| `api_url` | string (URL) | Its entry in this API (v1). | Never |
| `website` | string | Its website as we store it: usually a bare domain like `stripe.com`, sometimes a URL. | We don’t know it. |
| `checked_at` | string (ISO 8601 time) | When we last read its careers page, RFC 3339 in UTC. Always within the last 48 hours. | Never |
| `open_roles` | integer | Roles listed on its careers page at that read. Always at least 1. | Never |
| `snoozed` | boolean | You snoozed it: its roles stay out of your email and your New list until the snooze ends. We keep reading its careers page. Set with `POST {slug}/snooze`, clear with `DELETE {slug}/snooze`. | Never |
| `snoozed_until` | string (ISO 8601 time) | When the snooze ends, RFC 3339 in UTC: midnight at the start of that day in your time zone. | Not snoozed, or snoozed until you turn it back on (`snoozed` says which). |
| `opened_last_7_days` | integer | Roles first seen in the last 7 days. | We haven’t read the board long enough, or without gaps, to back a number. |
| `matching_roles` | integer | Open roles whose title contains `title` (all open roles without it), across every page. | Never |
| `newest_roles` | array of Role | This page of open roles, newest first: the 10 newest unless you send `page_size`, only titles containing `title` when you send it. | Never |
| `next_page_token` | string | Pass it as `page_token`, with the same `title`, for the next page of `newest_roles`. Opaque: don’t parse or build it. | This is the last page. |

Each item in `newest_roles` (Role):

| Field | Type | Meaning | Null when |
| --- | --- | --- | --- |
| `title` | string | The role as the careers page titles it. | Never |
| `location` | string | Where, as the careers page says it. | The posting names no location. |
| `apply_url` | string (URL) | The posting on the employer’s own site. | Never |
| `first_seen_at` | string (ISO 8601 time) | When the role opened, as near as we know: the read that first found it on a board we were already reading. RFC 3339 in UTC. | The role was already open at our first read of the board, so we don’t know when it opened; or the same rule as `opened_last_7_days`. |
| `first_read_at` | string (ISO 8601 time) | When roles.watch first saw the role, RFC 3339 in UTC. Always set, also for roles already open at our first read. | Never |

## Add or remove a company

These need a read + write key: make one in your account. A read-only key gets 403 `insufficient_scope`.

```
POST /api/public/v1/companies
```

```bash
curl -X POST -H "Authorization: Bearer rw_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"careers_url": "https://jobs.ashbyhq.com/example"}' \
  https://roles.watch/api/public/v1/companies
```

- Send `careers_url` (best) or `name`. We find the job board, check we can read it, and add it to your list. The first read usually lands within minutes.
- It is safe to repeat: a company already on your list answers 200 with `result: already_watching` and nothing changes. A new one answers 201 with `result: added`.
- The answer has the company’s `slug` and `board`: `state` is `ok` or `stale` once read (with `open_roles`), `reading` before the first read, `unreadable` when we can’t read it, `paused` when we aren’t reading it. Until it is read, there is no role count: never read that as zero.
- When every place on your plan is in use, nothing is added: 409 `plan_limit`, with `limit` and `used`, so a script can stop. On the paid plan it also carries `help`, a mailto link: email it to raise your limit.
- A company we can’t track is 422 `cannot_track` with a `reason`: `not_found`, `ambiguous` (with `candidates`, each with a `careers_url` to send instead) or `unreadable`.

```
DELETE /api/public/v1/companies/{slug}
```

Removes the company from your list and frees its place. Only your list changes; the company stays in roles.watch for everyone else. One not on your list is 404 `not_found`.

## Snooze a company

Snooze a company you’ve applied to, or don’t want to hear about for a while: its roles stay out of your email and your New list until the snooze ends. It stays on your list, and we keep reading its careers page. Needs a read + write key.

```
POST /api/public/v1/companies/{slug}/snooze
```

```bash
curl -X POST -H "Authorization: Bearer rw_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"until": "2027-06-01"}' \
  https://roles.watch/api/public/v1/companies/anthropic/snooze
```

- Send `until`, the day it comes back (`YYYY-MM-DD`, after today and at most 5 years out), or `length`: `3m`, `6m` or `1y` from today, or `none`. With no body it stays snoozed until you turn it back on.
- The snooze ends at midnight at the start of that day in the time zone set in your account, the same as the Snooze menu in the app.
- It is safe to repeat: snoozing again sets the same state, with the new end. The answer has `snoozed` and `snoozed_until` (null when there is no end).
- A company not on your list is 404 `not_found`. A date that isn’t after today is 400 `invalid_parameter`.

```
DELETE /api/public/v1/companies/{slug}/snooze
```

Turns it back on: its new roles reach your email again. One that isn’t snoozed answers 200 with `result: not_snoozed`, and nothing changes. The list and each company show `snoozed` and `snoozed_until`, so you can see which are snoozed.

## Errors

Errors are problem details (RFC 9457), sent as `application/problem+json`. Match on `code`, never on `detail`. The `type` of each is `https://roles.watch/developers#error-{code}`, with `_` as `-`.

Error:

| Field | Type | Meaning | Null when |
| --- | --- | --- | --- |
| `type` | string (URL) | A URI for the kind of problem, one per `code` (RFC 9457). | Never |
| `title` | string | A short summary of that kind of problem. The same for every `code`. | Never |
| `status` | integer | The HTTP status code. | Never |
| `detail` | string | What went wrong this time, in a sentence. Wording may change; match on `code`. | Never |
| `code` | string | Stable: `invalid_parameter`, `unauthorized`, `forbidden`, `paid_plan_required`, `not_found`, `rate_limited`, `insufficient_scope`, `plan_limit`, `cannot_track`. | Never |
| `upgrade_url` | string (URL) | Where to watch more companies. | Any error but `forbidden` and `paid_plan_required`. |

| Status | `code` | When | What to do |
| --- | --- | --- | --- |
| 304 | – | You sent `If-None-Match` with the current `ETag`. | Use the copy you have. |
| 308 | – | You used another spelling, the domain or an old id, of a company you watch. | Follow `Location` (`curl -L`, which keeps your key on the same host), and use that URL next time. |
| 400 | `invalid_parameter` | `q`, `title`, `page_size` or `page_token` is out of range, or the token came from another `q` or `title`. | `detail` says which one. |
| 401 | `unauthorized` | No key, or a key that was revoked. | Send `Authorization: Bearer rw_…`. Create a key in your account. |
| 403 | `forbidden` | A company you don’t watch, one over your plan’s limit, or one we don’t list. | Add it to your list, or upgrade at `upgrade_url`. |
| 403 | `paid_plan_required` | Your account isn’t on the paid plan: it never was, or it was downgraded. Your keys are kept. | Upgrade at `upgrade_url`, and the same keys work again. |
| 403 | `insufficient_scope` | An add, remove or snooze with a read-only key. | Make a read + write key in your account. |
| 404 | `not_found` | No such resource. A company we don’t list answers 403 (`forbidden`) to a key instead, so a key can’t probe which companies we read. A company you watch that has nothing to show yet (not read yet, a page we couldn’t read, or no open roles) is a 404 whose `detail` says which. | Check the `slug` against the list. For a company you watch, read `detail`: it is never zero roles. |
| 409 | `plan_limit` | An add when every place on your plan is in use. Nothing was added. The error carries `limit` and `used`, and on the paid plan `help`. | Remove a company, then add again, or email the `help` address to raise your limit. |
| 422 | `cannot_track` | An add we can’t do: `reason` is `not_found`, `ambiguous` (with `candidates`) or `unreadable`. Nothing was added. | Send the careers page URL, or pick one of `candidates`. |
| 429 | `rate_limited` | Over the hourly limit for your key or your address, or over 60 adds, removes and snoozes an hour. | Wait the seconds in `Retry-After`. |

## Rate limit and caching

- 120 requests an hour per key, and 300 an hour per IP address, across the API and the MCP server.
- Every answer says so in `RateLimit-Policy` (`"ip";q=300;w=3600, "key";q=120;w=3600`), and answers for a key say what is left in `RateLimit` (`"key";r=…;t=…`: `r` requests for `t` more seconds). Both follow the IETF RateLimit header draft.
- Over either limit you get 429 with `Retry-After` in seconds. Wait that long, then carry on.
- Asking more often doesn’t get fresher data: we check each careers page every few hours, and answers are cached for up to two hours.
- Answers for a key are never cached by a CDN or a shared cache (`Cache-Control: private, no-store`). The keyless list is cached for up to two hours.
- Every answer has an `ETag`. Send it back as `If-None-Match` and an unchanged answer is 304 with no body.
- With a key, a 304 doesn’t count against the per-IP limit or the key’s 120 an hour, so a key that has used its hour can still check what changed. 304s have their own 1200 an hour per key, then 429 with `Retry-After`. A 304 carries the same `RateLimit-Policy` and `RateLimit` headers as a 200, showing the normal limits.
- The API only returns what we have already stored. It never reads a careers page because you asked.

## Build a request

Pick a company to see the exact request. Paste your key to see its live answer for a company you watch; the key stays in this tab and is sent only to roles.watch.

## MCP server

On the paid plan, Claude Code, Cursor and VS Code can look up the companies you watch through the roles.watch MCP server. Create a key in your account, then put it in the config below in place of `rw_YOUR_KEY`. With a read-only key it reads; with a read + write key it can also add, remove and snooze companies on your list. It never sees anyone else’s. Same facts, same key and same limits as the API.

**Claude Code**

```
claude mcp add --transport http roles-watch https://roles.watch/api/public/mcp \
  --header "Authorization: Bearer rw_YOUR_KEY"
```

**Cursor**

Add this to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project:

```
{
  "mcpServers": {
    "roles-watch": {
      "url": "https://roles.watch/api/public/mcp",
      "headers": {
        "Authorization": "Bearer rw_YOUR_KEY"
      }
    }
  }
}
```

**VS Code**

Add this to .vscode/mcp.json in your workspace:

```
{
  "servers": {
    "roles-watch": {
      "type": "http",
      "url": "https://roles.watch/api/public/mcp",
      "headers": {
        "Authorization": "Bearer rw_YOUR_KEY"
      }
    }
  }
}
```

Then ask it: “What’s new at Anthropic this week?”

| Tool | Arguments | Returns |
| --- | --- | --- |
| `list_companies` | `query` (optional, up to 60 characters), `page_size` (1 to 25, default 10), `page_token` | The same list as `GET /api/public/v1/companies` with your key: `companies`, `next_page_token` and `total_size` |
| `get_company` | `slug`, or the company’s website domain | The same Company as `GET /api/public/v1/companies/{slug}` |
| `check_companies` | `items`: 1 to 25 names or careers page URLs | For each, without changing anything: `watching`, `on_list_not_watched`, `known`, `unsupported`, `ambiguous` or `unknown`, and the board’s state when we know it |
| `add_companies` | `items`: 1 to 10; `confirm_token` from the preview | Without `confirm_token`, a preview and a token (nothing changes). With it, what changed: `added`, `already_watching`, `could_not_track`, `not_attempted`. Read + write key |
| `remove_company` | `slug`, or the company’s website domain | What changed. Read + write key |
| `snooze_company` | `slug`; `until` (`YYYY-MM-DD`) or `length` (`3m`, `6m`, `1y`, `none`), or neither for no end | The same answer as `POST /api/public/v1/companies/{slug}/snooze`. Read + write key |
| `unsnooze_company` | `slug`, or the company’s website domain | The same answer as `DELETE /api/public/v1/companies/{slug}/snooze`. Read + write key |

list_companies and get_company declare an `outputSchema`. A company you don’t watch, a read-only key on a write tool, or an out-of-range argument, comes back as a tool error (`isError: true`) whose text is the API’s problem document, with the same `code`. Without a key the server answers HTTP 401; over 120 requests an hour per key or 300 per address, HTTP 429 with `Retry-After`. Endpoint: `https://roles.watch/api/public/mcp` (Streamable HTTP, JSON answers).

## Versioning and deprecation

- v1 is the only version, and it is in the path: `/api/public/v1/companies`. The paths from before it, `/api/public/companies`…, answer 308 to the same path under v1.
- Within v1, fields and endpoints are only added: none is renamed, removed or changes type, and no error `code` changes meaning. Ignore fields you don’t know.
- A breaking change would ship as v2, announced on this page and in the [changelog](https://roles.watch/changelog) first. v1 would then keep working for at least 6 months, and its answers would carry a `Deprecation` header and, once the date is set, `Sunset`.

## For agents

- [/api/public/openapi.json](https://roles.watch/api/public/openapi.json): the OpenAPI 3.1 spec, built from the same field list as this page (also at [/openapi.json](https://roles.watch/openapi.json)).
- [/developers.md](https://roles.watch/developers.md): this page as markdown.
- [/llms.txt](https://roles.watch/llms.txt): an index of roles.watch for language models.
- [/llms-full.txt](https://roles.watch/llms-full.txt): these docs in one file.
