Skip to content

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

  • Base URL: https://api.rollout.so. All public routes start with /v1.

  • Browser feed (/v1/feed, /v1/announcements/{id}/read): a publishable key in X-Rollout-Key plus the user’s identity. See Identity.

  • Server API (/v1/subjects): a secret key as Authorization: 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) and cursor, and return nextCursor, which is null on the last page.

  • Errors share one shape, with a machine-readable error code:

    { "error": "invalid_token", "message": "Invalid or expired identity token" }

    Validation errors use validation_failed and add issues.

  • 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.

A full feed item carries its body three times (html, markdown, text). For lists, badges and small teasers you rarely need that:

  • view=summary on 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=true returns only unread announcements; unreadCount still 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/highlight returns the one to tease now (of the newest unread announcement that has one) or { "highlight": null }, with the snippet’s title, tag, text and image, and the announcementId to open.
  • Closing a teaser: POST /v1/announcements/{id}/highlight/dismiss hides it for that user on every device. The announcement stays unread, and a re-notify shows the teaser again.