API reference
Every public endpoint, with request and response schemas and a place to try it, is in the interactive reference served by the API.
Open the REST API reference
Conventions
Section titled “Conventions”-
Base URL:
https://api.rollout.so. All public routes start with/v1. -
Browser feed (
/v1/feed,/v1/announcements/{id}/read): a publishable key inX-Rollout-Keyplus the user’s identity. See Identity. -
Server API (
/v1/subjects): a secret key asAuthorization: Bearer sk_live_…. See Server API. -
Public changelog (
/v1/changelogs/{slug}): no authentication. See Public changelog. -
Pagination: list endpoints take
limit(1–50, default 20) andcursor, and returnnextCursor, which isnullon the last page. -
Errors share one shape, with a machine-readable
errorcode:{ "error": "invalid_token", "message": "Invalid or expired identity token" }Validation errors use
validation_failedand addissues. -
Lists and teasers: see below.
-
Rate limits: 300 requests per minute per API key and client IP, and 1200 per minute per IP overall. After 60 failed authentications in a minute, an IP is refused for a while. Both answer
429 rate_limited.
Lists and teasers
Section titled “Lists and teasers”A full feed item carries its body three times (html, markdown, text). For lists, badges and
small teasers you rarely need that:
view=summaryon the feed leaves the bodies out. Load one announcement in full when it’s opened:GET /v1/announcements/{id}(or/v1/subjects/{id}/announcements/{announcementId}).unread=truereturns only unread announcements;unreadCountstill counts all of them.- The highlight: an announcement can name one of its snippets as its highlight, with an
optional teaser text.
GET /v1/feed/highlightreturns the one to tease now (of the newest unread announcement that has one) or{ "highlight": null }, with the snippet’stitle,tag,textandimage, and theannouncementIdto open. - Closing a teaser:
POST /v1/announcements/{id}/highlight/dismisshides it for that user on every device. The announcement stays unread, and a re-notify shows the teaser again.