{"openapi":"3.1.0","info":{"title":"roles.watch API","version":"1","description":"For roles.watch users: the companies you watch, checked every few hours, and their open roles. API and MCP are included with the paid plan; a key on a free account answers 403 (code: paid_plan_required). Send a personal key (create one in your account menu) as Authorization: Bearer rw_…; a key reads only your own watched companies. A read-only key reads; a read + write key can also add companies to your list (POST), remove them (DELETE), and snooze them or turn them back on ({slug}/snooze). Without a key, the list answers names and links only. Within v1, fields and endpoints are only ever added, never renamed or removed. Errors are RFC 9457 problem documents; match on code."},"servers":[{"url":"https://roles.watch"}],"externalDocs":{"url":"https://roles.watch/developers"},"paths":{"/api/public/v1/companies":{"get":{"operationId":"listCompanies","summary":"With a key, the companies you watch; without one, names and links only","description":"Pages with page_size and page_token; follow next_page_token until it is null.","security":[{"apiKey":[]},{}],"parameters":[{"name":"q","in":"query","required":false,"description":"Optional. Only companies whose name, slug or website contains it, ignoring case. Up to 60 characters.","schema":{"type":"string","maxLength":60}},{"name":"page_size","in":"query","required":false,"description":"Optional. Companies per page, 1 to 100. Default 50.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"page_token","in":"query","required":false,"description":"Optional. A next_page_token from the previous page. Send the same q with it.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IfNoneMatch"}],"responses":{"200":{"description":"A page of companies, sorted by slug: CompanyList with a key, CompanyDirectory without one.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CompanyList"},{"$ref":"#/components/schemas/CompanyDirectory"}]}}}},"304":{"description":"Not modified: your `If-None-Match` has the current ETag. No body. Carries the same RateLimit and RateLimit-Policy as a 200. With a key it counts against neither the per-IP limit nor the key's 120 an hour: 304s have their own 1200 an hour per key, then 429.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"description":"A parameter is out of range, or page_token is from another q (code: invalid_parameter).","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No key, or a revoked one (code: unauthorized). Create a key in your account menu.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"roles.watch\""}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"With a key: your account isn’t on the paid plan, so the key is suspended until you upgrade (code: paid_plan_required). See upgrade_url.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Over 120 requests an hour for one key, 1200 304s an hour for one key, or 300 from one IP address (code: rate_limited). Wait Retry-After seconds.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"addCompany","summary":"Add one company to your list (needs a read + write key)","description":"Send the company’s careers page URL (best) or its name. We find its job board, check we can read it, and add it; the first read usually lands within minutes. Idempotent: a company already on your list answers 200 with it and changes nothing. A company reached by another URL (its website, another link to the same board) is the same company.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"careers_url":{"type":"string","format":"uri","maxLength":2048,"description":"The company’s careers page or job board URL, http(s)."},"name":{"type":"string","maxLength":100,"description":"The company’s name, when you don’t have the URL. Send one of the two."}}}}}},"responses":{"200":{"description":"Already on your list (result: already_watching), or on it and now watched (result: now_watching). Nothing else changed.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddResult"}}}},"201":{"description":"Added (result: added). company.board says whether we have read it yet.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddResult"}}}},"400":{"description":"The body isn’t { careers_url } or { name } (code: invalid_parameter).","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No key, or a revoked one (code: unauthorized). Create a key in your account menu.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"roles.watch\""}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"A read-only key (code: insufficient_scope), or your account isn’t on the paid plan (code: paid_plan_required).","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Every place on your plan is in use, so nothing was added (code: plan_limit). The problem carries limit (places on your plan) and used (places taken). Remove a company, then add again. On the paid plan, help is a mailto link: email it to raise your limit.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"We can’t track this company (code: cannot_track). reason is not_found (no careers page found for that name), ambiguous (several companies match; candidates lists up to 5 with careers_url) or unreadable (a site we can’t read; detail says why, and manual_check_url, when present, is the page to check by hand). Nothing was added.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Over 120 requests an hour for one key, 300 from one IP address, 60 adds, removes and snoozes an hour for one account, or too many new companies to look up this hour (code: rate_limited). Wait Retry-After seconds.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/public/v1/companies/{slug}":{"get":{"operationId":"getCompany","summary":"One company you watch, with a page of its open roles, newest first","description":"The 10 newest open roles by default. title filters them; page through with page_size and page_token until next_page_token is null.","security":[{"apiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"description":"A slug from the list. Another spelling, the company’s domain or its old id answers 308 to the canonical URL.","schema":{"type":"string"}},{"name":"title","in":"query","required":false,"description":"Optional. Only roles whose title contains it, ignoring case. Up to 60 characters.","schema":{"type":"string"}},{"name":"page_size","in":"query","required":false,"description":"Optional. Roles per page, 1 to 100. Default 10.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"page_token","in":"query","required":false,"description":"Optional. A next_page_token from the previous page of this company. Send the same title with it.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IfNoneMatch"}],"responses":{"200":{"description":"The company, with one page of its open roles.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"304":{"description":"Not modified: your `If-None-Match` has the current ETag. No body. Carries the same RateLimit and RateLimit-Policy as a 200. With a key it counts against neither the per-IP limit nor the key's 120 an hour: 304s have their own 1200 an hour per key, then 429.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"ETag":{"$ref":"#/components/headers/ETag"}}},"308":{"description":"An alias of a company you watch. Location is the canonical URL.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"Location":{"schema":{"type":"string"}}}},"400":{"description":"title, page_size or page_token is out of range, or page_token is from another title (code: invalid_parameter).","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No key, or a revoked one (code: unauthorized). Create a key in your account menu.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"roles.watch\""}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Not a company you watch, over your plan’s limit, or not one we list (code: forbidden); or your account isn’t on the paid plan (code: paid_plan_required). See upgrade_url.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"A company you watch with nothing to show yet: not read yet, a careers page we couldn’t read, or no open roles at the last read (code: not_found). detail says which. Never read this as zero roles.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Over 120 requests an hour for one key, 1200 304s an hour for one key, or 300 from one IP address (code: rate_limited). Wait Retry-After seconds.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"removeCompany","summary":"Stop watching one company (needs a read + write key)","description":"Removes the company from your list and frees its place. Only your list changes: the company stays in roles.watch for everyone else.","security":[{"apiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"description":"A slug from the list. Another spelling, the company’s domain or its old id answers 308 to the canonical URL.","schema":{"type":"string"}}],"responses":{"200":{"description":"Removed. summary says what changed.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveResult"}}}},"401":{"description":"No key, or a revoked one (code: unauthorized). Create a key in your account menu.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"roles.watch\""}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"A read-only key (code: insufficient_scope), or your account isn’t on the paid plan (code: paid_plan_required).","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not on your list, so nothing was removed (code: not_found).","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Over 120 requests an hour for one key, 300 from one IP address, 60 adds, removes and snoozes an hour for one account, or too many new companies to look up this hour (code: rate_limited). Wait Retry-After seconds.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/public/v1/companies/{slug}/snooze":{"post":{"operationId":"snoozeCompany","summary":"Snooze one company on your list (needs a read + write key)","description":"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. Send until (a date in your time zone), or length (3m, 6m or 1y from today, or none), or no body: snoozed until you turn it back on. Idempotent: snoozing again sets the same state, with the new end. The company’s snoozed and snoozed_until show it.","security":[{"apiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"description":"A slug from the list. Another spelling, the company’s domain or its old id answers 308 to the canonical URL.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"until":{"type":"string","format":"date","description":"The day it comes back, YYYY-MM-DD in your time zone: after today, and at most 5 years out."},"length":{"type":"string","enum":["3m","6m","1y","none"],"description":"How long instead of a date: 3m, 6m or 1y from today, or none (until you turn it back on). Send until or length, not both."}}}}}},"responses":{"200":{"description":"Snoozed (result: snoozed). snoozed_until is when it ends, or null for no end.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnoozeResult"}}}},"400":{"description":"The body isn’t {}, { until } or { length }, or until isn’t a date after today (code: invalid_parameter).","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No key, or a revoked one (code: unauthorized). Create a key in your account menu.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"roles.watch\""}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"A read-only key (code: insufficient_scope), or your account isn’t on the paid plan (code: paid_plan_required).","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not on your list, so nothing was snoozed (code: not_found).","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Over 120 requests an hour for one key, 300 from one IP address, 60 adds, removes and snoozes an hour for one account, or too many new companies to look up this hour (code: rate_limited). Wait Retry-After seconds.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"unsnoozeCompany","summary":"Turn a snoozed company back on (needs a read + write key)","description":"Its new roles reach your email again. Idempotent: one that isn’t snoozed answers 200 with result not_snoozed and nothing changes.","security":[{"apiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"description":"A slug from the list. Another spelling, the company’s domain or its old id answers 308 to the canonical URL.","schema":{"type":"string"}}],"responses":{"200":{"description":"Back on (result: unsnoozed), or it wasn’t snoozed (result: not_snoozed).","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnoozeResult"}}}},"401":{"description":"No key, or a revoked one (code: unauthorized). Create a key in your account menu.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"roles.watch\""}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"A read-only key (code: insufficient_scope), or your account isn’t on the paid plan (code: paid_plan_required).","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not on your list (code: not_found).","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Over 120 requests an hour for one key, 300 from one IP address, 60 adds, removes and snoozes an hour for one account, or too many new companies to look up this hour (code: rate_limited). Wait Retry-After seconds.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"A personal roles.watch key, rw_…, from your account menu."}},"parameters":{"IfNoneMatch":{"name":"If-None-Match","in":"header","required":false,"description":"An ETag from an earlier answer. If it is still current, the answer is 304 with no body.","schema":{"type":"string"}}},"headers":{"RateLimit-Policy":{"description":"The limits that apply (draft-ietf-httpapi-ratelimit-headers): \"ip\";q=300;w=3600, and \"key\";q=120;w=3600 with a key.","schema":{"type":"string"}},"RateLimit":{"description":"What is left of each limit: r requests, for t more seconds. Not sent on the keyless list, which a CDN caches.","schema":{"type":"string"}},"ETag":{"description":"A validator for this answer. Send it back as If-None-Match.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds until you may retry.","schema":{"type":"integer"}}},"schemas":{"CompanyList":{"type":"object","required":["companies","next_page_token","total_size"],"additionalProperties":true,"properties":{"companies":{"type":"array","items":{"$ref":"#/components/schemas/CompanySummary"},"description":"This page of companies, sorted by slug. At most page_size."},"next_page_token":{"type":["string","null"],"description":"Pass it as page_token, with the same q, for the next page. Opaque: don’t parse or build it. Null when: This is the last page."},"total_size":{"type":"integer","description":"Companies you watch that match q (or all of them), across every page."}}},"CompanyDirectory":{"type":"object","required":["companies","next_page_token","total_size"],"additionalProperties":true,"properties":{"companies":{"type":"array","items":{"$ref":"#/components/schemas/CompanyLink"},"description":"This page of companies, sorted by slug. At most page_size."},"next_page_token":{"type":["string","null"],"description":"Pass it as page_token, with the same q, for the next page. Opaque: don’t parse or build it. Null when: This is the last page."},"total_size":{"type":"integer","description":"Companies we list that match q (or all of them), across every page."}}},"CompanyLink":{"type":"object","required":["name","slug","page_url"],"additionalProperties":true,"properties":{"name":{"type":"string","description":"The company name."},"slug":{"type":"string","description":"Its id in our URLs. Stable while the name is."},"page_url":{"type":"string","format":"uri","description":"Its public page on roles.watch."}}},"CompanySummary":{"type":"object","required":["name","slug","page_url","api_url","website","checked_at","open_roles","snoozed","snoozed_until"],"additionalProperties":true,"properties":{"name":{"type":"string","description":"The company name."},"slug":{"type":"string","description":"Its id in our URLs. Stable while the name is."},"page_url":{"type":"string","format":"uri","description":"Its public page on roles.watch."},"api_url":{"type":"string","format":"uri","description":"Its entry in this API (v1)."},"website":{"type":["string","null"],"description":"Its website as we store it: usually a bare domain like stripe.com, sometimes a URL. Null when: We don’t know it."},"checked_at":{"type":"string","format":"date-time","description":"When we last read its careers page, RFC 3339 in UTC. Always within the last 48 hours."},"open_roles":{"type":"integer","description":"Roles listed on its careers page at that read. Always at least 1."},"snoozed":{"type":"boolean","description":"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."},"snoozed_until":{"type":["string","null"],"format":"date-time","description":"When the snooze ends, RFC 3339 in UTC: midnight at the start of that day in your time zone. Null when: Not snoozed, or snoozed until you turn it back on (snoozed says which)."}}},"Company":{"type":"object","required":["name","slug","page_url","api_url","website","checked_at","open_roles","snoozed","snoozed_until","opened_last_7_days","matching_roles","newest_roles","next_page_token"],"additionalProperties":true,"properties":{"name":{"type":"string","description":"The company name."},"slug":{"type":"string","description":"Its id in our URLs. Stable while the name is."},"page_url":{"type":"string","format":"uri","description":"Its public page on roles.watch."},"api_url":{"type":"string","format":"uri","description":"Its entry in this API (v1)."},"website":{"type":["string","null"],"description":"Its website as we store it: usually a bare domain like stripe.com, sometimes a URL. Null when: We don’t know it."},"checked_at":{"type":"string","format":"date-time","description":"When we last read its careers page, RFC 3339 in UTC. Always within the last 48 hours."},"open_roles":{"type":"integer","description":"Roles listed on its careers page at that read. Always at least 1."},"snoozed":{"type":"boolean","description":"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."},"snoozed_until":{"type":["string","null"],"format":"date-time","description":"When the snooze ends, RFC 3339 in UTC: midnight at the start of that day in your time zone. Null when: Not snoozed, or snoozed until you turn it back on (snoozed says which)."},"opened_last_7_days":{"type":["integer","null"],"description":"Roles first seen in the last 7 days. Null when: We haven’t read the board long enough, or without gaps, to back a number."},"matching_roles":{"type":"integer","description":"Open roles whose title contains title (all open roles without it), across every page."},"newest_roles":{"type":"array","items":{"$ref":"#/components/schemas/Role"},"description":"This page of open roles, newest first: the 10 newest unless you send page_size, only titles containing title when you send it."},"next_page_token":{"type":["string","null"],"description":"Pass it as page_token, with the same title, for the next page of newest_roles. Opaque: don’t parse or build it. Null when: This is the last page."}}},"Role":{"type":"object","required":["title","location","apply_url","first_seen_at","first_read_at"],"additionalProperties":true,"properties":{"title":{"type":"string","description":"The role as the careers page titles it."},"location":{"type":["string","null"],"description":"Where, as the careers page says it. Null when: The posting names no location."},"apply_url":{"type":"string","format":"uri","description":"The posting on the employer’s own site."},"first_seen_at":{"type":["string","null"],"format":"date-time","description":"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. Null when: 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":{"type":"string","format":"date-time","description":"When roles.watch first saw the role, RFC 3339 in UTC. Always set, also for roles already open at our first read."}}},"Problem":{"type":"object","required":["type","title","status","detail","code","upgrade_url"],"additionalProperties":true,"properties":{"type":{"type":"string","format":"uri","description":"A URI for the kind of problem, one per code (RFC 9457)."},"title":{"type":"string","description":"A short summary of that kind of problem. The same for every code."},"status":{"type":"integer","description":"The HTTP status code."},"detail":{"type":"string","description":"What went wrong this time, in a sentence. Wording may change; match on code."},"code":{"type":"string","description":"Stable: invalid_parameter, unauthorized, forbidden, paid_plan_required, not_found, rate_limited, insufficient_scope, plan_limit, cannot_track.","enum":["invalid_parameter","unauthorized","forbidden","paid_plan_required","not_found","rate_limited","insufficient_scope","plan_limit","cannot_track"]},"upgrade_url":{"type":["string","null"],"format":"uri","description":"Where to watch more companies. Null when: Any error but forbidden and paid_plan_required."}}},"AddResult":{"type":"object","required":["result","company","summary"],"additionalProperties":true,"properties":{"result":{"type":"string","enum":["added","already_watching","now_watching"],"description":"What happened."},"company":{"type":"object","required":["name","slug","website","careers_url","watched","board","api_url"],"additionalProperties":true,"properties":{"name":{"type":"string","description":"The company name."},"slug":{"type":"string","description":"Its id in our URLs; use it with DELETE."},"website":{"type":["string","null"],"description":"Its website as we store it. Null when we don’t know it."},"careers_url":{"type":["string","null"],"description":"The careers page we read."},"watched":{"type":"boolean","description":"Within your plan: checked on schedule and readable with your key."},"board":{"type":"object","required":["state","readable","last_read_at","open_roles","detail"],"additionalProperties":true,"description":"What we know about the company’s careers page. A board we haven’t read, or can’t, is never reported as having no roles.","properties":{"state":{"type":"string","enum":["reading","ok","stale","unreadable","paused"],"description":"ok: read in the last 48 hours. stale: read before that. reading: not read yet. unreadable: we can’t read it. paused: not being read."},"readable":{"type":["boolean","null"],"description":"True when we have read it, false when we can’t, null until the first read."},"last_read_at":{"type":["string","null"],"format":"date-time","description":"When we last read it, RFC 3339. Null when never."},"open_roles":{"type":["integer","null"],"description":"Open roles at that read. Null unless state is ok or stale."},"detail":{"type":"string","description":"One sentence for a person."}}},"api_url":{"type":"string","format":"uri","description":"Its entry in this API, once we have read it and it has open roles."}}},"summary":{"type":"string","description":"What changed, in a sentence."}}},"RemoveResult":{"type":"object","required":["result","slug","name","summary"],"additionalProperties":true,"properties":{"result":{"type":"string","enum":["removed"]},"slug":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string","description":"What changed, in a sentence."}}},"SnoozeResult":{"type":"object","required":["result","slug","name","snoozed","snoozed_until","summary"],"additionalProperties":true,"properties":{"result":{"type":"string","enum":["snoozed","unsnoozed","not_snoozed"],"description":"What happened. not_snoozed: an unsnooze of a company that wasn’t snoozed; nothing changed."},"slug":{"type":"string"},"name":{"type":"string"},"snoozed":{"type":"boolean","description":"Whether it is snoozed now."},"snoozed_until":{"type":["string","null"],"format":"date-time","description":"When the snooze ends, RFC 3339 in UTC (midnight at the start of that day in your time zone). Null when not snoozed, or snoozed until you turn it back on."},"summary":{"type":"string","description":"What changed, in a sentence."}}}}}}