Public API
v1On 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, for your own list only, and nothing about anyone else. A read + write key can also add, remove and snooze companies on your list.
Try it#
Sign in, 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:
curl -H "Authorization: Bearer rw_YOUR_KEY" \ https://roles.watch/api/public/v1/companies/anthropic
For someone who watches Anthropic, it answers with what we read from its careers page:
{
"name": "Anthropic",
"slug": "anthropic",
"page_url": "https://roles.watch/companies/anthropic",
"api_url": "https://roles.watch/api/public/v1/companies/anthropic",
"website": "anthropic.com",
"checked_at": "2026-11-18T19:40:21.352Z",
"open_roles": 648,
"snoozed": false,
"snoozed_until": null,
"opened_last_7_days": 36,
"matching_roles": 10,
"newest_roles": [
{
"title": "Applied AI Engineer, Commercial",
"location": "San Francisco, CA",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5483945008",
"first_seen_at": "2026-11-18T19:40:20.004Z",
"first_read_at": "2026-11-18T19:40:20.004Z"
},
{
"title": "Account Executive, Quantitative Trading & Investing",
"location": "London, UK",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5484875008",
"first_seen_at": "2026-11-18T15:40:08.890Z",
"first_read_at": "2026-11-18T15:40:08.890Z"
},
{
"title": "[Paris] Applied AI Architect, Industries",
"location": "Paris, France",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5482967008",
"first_seen_at": "2026-11-18T12:00:05.658Z",
"first_read_at": "2026-11-18T12:00:05.658Z"
},
{
"title": "Strategic Pursuits Lead, DACH",
"location": "Munich, Germany",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5486380008",
"first_seen_at": "2026-11-18T12:00:05.658Z",
"first_read_at": "2026-11-18T12:00:05.658Z"
},
{
"title": "Machine Learning Data Scientist, Forecasting Platform",
"location": "San Francisco, CA",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5467893008",
"first_seen_at": "2026-11-18T04:00:15.203Z",
"first_read_at": "2026-11-18T04:00:15.203Z"
},
{
"title": "Compute Capacity Strategy & Operations",
"location": "San Francisco, CA",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5485582008",
"first_seen_at": "2026-11-18T00:10:07.862Z",
"first_read_at": "2026-11-18T00:10:07.862Z"
},
{
"title": "Developer Relations, Platform",
"location": "San Francisco, CA",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5206870008",
"first_seen_at": "2026-11-18T00:10:07.862Z",
"first_read_at": "2026-11-18T00:10:07.862Z"
},
{
"title": "GTM Activations Strategy Lead",
"location": "San Francisco, CA",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5483359008",
"first_seen_at": "2026-11-18T00:10:07.862Z",
"first_read_at": "2026-11-18T00:10:07.862Z"
},
{
"title": "Web Strategy Lead",
"location": "San Francisco, CA",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5465637008",
"first_seen_at": "2026-11-17T20:20:06.125Z",
"first_read_at": "2026-11-17T20:20:06.125Z"
},
{
"title": "Partner Marketing Manager, Cloud Partners EMEA",
"location": "London, UK",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5473999008",
"first_seen_at": "2026-11-17T16:20:12.232Z",
"first_read_at": "2026-11-17T16:20:12.232Z"
}
],
"next_page_token": null
}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. |
curl -H "Authorization: Bearer rw_YOUR_KEY" \ "https://roles.watch/api/public/v1/companies?page_size=3"
For someone who watches Anthropic, OpenAI and Stripe:
{
"companies": [
{
"name": "Anthropic",
"slug": "anthropic",
"page_url": "https://roles.watch/companies/anthropic",
"api_url": "https://roles.watch/api/public/v1/companies/anthropic",
"website": "anthropic.com",
"checked_at": "2026-11-18T19:40:21.352Z",
"open_roles": 648,
"snoozed": false,
"snoozed_until": null
},
{
"name": "OpenAI",
"slug": "openai",
"page_url": "https://roles.watch/companies/openai",
"api_url": "https://roles.watch/api/public/v1/companies/openai",
"website": "openai.com",
"checked_at": "2026-11-18T20:50:17.882Z",
"open_roles": 838,
"snoozed": false,
"snoozed_until": null
},
{
"name": "Stripe",
"slug": "stripe",
"page_url": "https://roles.watch/companies/stripe",
"api_url": "https://roles.watch/api/public/v1/companies/stripe",
"website": "stripe.com",
"checked_at": "2026-11-18T22:02:13.985Z",
"open_roles": 786,
"snoozed": false,
"snoozed_until": null
}
],
"next_page_token": null,
"total_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.
curl "https://roles.watch/api/public/v1/companies?q=ramp"
{
"companies": [
{
"name": "Ramp",
"slug": "ramp",
"page_url": "https://roles.watch/companies/ramp"
}
],
"next_page_token": null,
"total_size": 1
}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. |
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.
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
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) orname. 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_watchingand nothing changes. A new one answers 201 withresult: added. - The answer has the company’s
slugandboard:stateisokorstaleonce read (withopen_roles),readingbefore the first read,unreadablewhen we can’t read it,pausedwhen 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, withlimitandused, so a script can stop. On the paid plan it also carrieshelp, a mailto link: email it to raise your limit. - A company we can’t track is 422
cannot_trackwith areason:not_found,ambiguous(withcandidates, each with acareers_urlto send instead) orunreadable.
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}/snoozecurl -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), orlength:3m,6mor1yfrom today, ornone. 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
snoozedandsnoozed_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 400invalid_parameter.
DELETE /api/public/v1/companies/{slug}/snoozeTurns 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 inRateLimit("key";r=…;t=…:rrequests fortmore seconds). Both follow the IETF RateLimit header draft. - Over either limit you get 429 with
Retry-Afterin 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 asIf-None-Matchand 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 sameRateLimit-PolicyandRateLimitheaders 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.
GET https://roles.watch/api/public/v1/companies/anthropicHTTP 200
{
"name": "Anthropic",
"slug": "anthropic",
"page_url": "https://roles.watch/companies/anthropic",
"api_url": "https://roles.watch/api/public/v1/companies/anthropic",
"website": "anthropic.com",
"checked_at": "2026-11-18T19:40:21.352Z",
"open_roles": 648,
"snoozed": false,
"snoozed_until": null,
"opened_last_7_days": 36,
"matching_roles": 10,
"newest_roles": [
{
"title": "Applied AI Engineer, Commercial",
"location": "San Francisco, CA",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5483945008",
"first_seen_at": "2026-11-18T19:40:20.004Z",
"first_read_at": "2026-11-18T19:40:20.004Z"
},
{
"title": "Account Executive, Quantitative Trading & Investing",
"location": "London, UK",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5484875008",
"first_seen_at": "2026-11-18T15:40:08.890Z",
"first_read_at": "2026-11-18T15:40:08.890Z"
},
{
"title": "[Paris] Applied AI Architect, Industries",
"location": "Paris, France",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5482967008",
"first_seen_at": "2026-11-18T12:00:05.658Z",
"first_read_at": "2026-11-18T12:00:05.658Z"
},
{
"title": "Strategic Pursuits Lead, DACH",
"location": "Munich, Germany",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5486380008",
"first_seen_at": "2026-11-18T12:00:05.658Z",
"first_read_at": "2026-11-18T12:00:05.658Z"
},
{
"title": "Machine Learning Data Scientist, Forecasting Platform",
"location": "San Francisco, CA",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5467893008",
"first_seen_at": "2026-11-18T04:00:15.203Z",
"first_read_at": "2026-11-18T04:00:15.203Z"
},
{
"title": "Compute Capacity Strategy & Operations",
"location": "San Francisco, CA",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5485582008",
"first_seen_at": "2026-11-18T00:10:07.862Z",
"first_read_at": "2026-11-18T00:10:07.862Z"
},
{
"title": "Developer Relations, Platform",
"location": "San Francisco, CA",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5206870008",
"first_seen_at": "2026-11-18T00:10:07.862Z",
"first_read_at": "2026-11-18T00:10:07.862Z"
},
{
"title": "GTM Activations Strategy Lead",
"location": "San Francisco, CA",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5483359008",
"first_seen_at": "2026-11-18T00:10:07.862Z",
"first_read_at": "2026-11-18T00:10:07.862Z"
},
{
"title": "Web Strategy Lead",
"location": "San Francisco, CA",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5465637008",
"first_seen_at": "2026-11-17T20:20:06.125Z",
"first_read_at": "2026-11-17T20:20:06.125Z"
},
{
"title": "Partner Marketing Manager, Cloud Partners EMEA",
"location": "London, UK",
"apply_url": "https://job-boards.greenhouse.io/anthropic/jobs/5473999008",
"first_seen_at": "2026-11-17T16:20:12.232Z",
"first_read_at": "2026-11-17T16:20:12.232Z"
}
],
"next_page_token": null
}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
codechanges meaning. Ignore fields you don’t know. - A breaking change would ship as v2, announced on this page and in the changelog first. v1 would then keep working for at least 6 months, and its answers would carry a
Deprecationheader and, once the date is set,Sunset.
For agents#
- /api/public/openapi.json: the OpenAPI 3.1 spec, built from the same field list as this page (also at /openapi.json).
- /developers.md: this page as markdown.
- /llms.txt: an index of roles.watch for language models.
- /llms-full.txt: these docs in one file.