Server API
The SDK runs in the browser. Your backend can use the same feed through the REST API, for example to show announcements in a native app, sync users ahead of time, or mark announcements read from an email click. The browser and your servers share read state for the same user.
Secret keys
Section titled “Secret keys”Create a secret key (sk_live_…) under Settings → Keys & origins. It’s shown once; store it like a
password and never ship it to a browser. Send it as a bearer token:
curl https://api.rollout.so/v1/subjects/sbj_… \ -H "Authorization: Bearer sk_live_…"Secret keys only work on /v1/subjects and /v1/consent-events, and publishable keys only on the browser feed, so
a leaked publishable key can’t act for arbitrary users.
-
Create or update the user by your own id.
POST /v1/subjectsis idempotent onuserId: it returns201for a new user and200otherwise. Fields you leave out keep their value.Terminal window curl -X POST https://api.rollout.so/v1/subjects \-H "Authorization: Bearer sk_live_…" -H "Content-Type: application/json" \-d '{"userId": "user_123", "orgId": "org_42", "createdAt": "2025-01-10T00:00:00Z", "attrs": {"plan": "pro"}}'Field Description userIdRequired. Your id for the user, any string up to 256 characters. orgIdThe user’s organization or account; nullclears it.createdAtWhen the user signed up; older announcements count as read. nullclears it.attrsCustom attributes for targeting. Replaces the stored attributes, max 16 KB. emailWhere announcement emails go; nullclears it. See Email and consent.consentConsent per purpose, see Email and consent. -
Keep the returned
id. It looks likesbj_…and addresses the user in paths. Your own user id only travels in request bodies, so it stays out of URLs and never needs encoding.
Email and consent
Section titled “Email and consent”rollout emails a user only with an address and their consent. The address comes from the email
claim of signed tokens or from email here. Tokens are sent on every visit, so if
they carry an address, theirs wins.
Consent is only ever set here, never by tokens. There is one purpose so far,
email.product_updates:
curl -X POST https://api.rollout.so/v1/subjects \ -H "Authorization: Bearer sk_live_…" -H "Content-Type: application/json" \ -d '{ "userId": "user_123", "email": "jane@acme.io", "consent": { "email.product_updates": { "status": "granted", "evidence": { "method": "signup_checkbox", "text": "Email me product updates", "at": "2025-01-10T09:30:00Z" } } } }'statusisgrantedordenied. Until you send one, it’sunknown, and unknown users get no emails unless the project allows it.evidenceis optional: how and when the user decided. rollout keeps it with every change.- Unsubscribes win. When a user unsubscribes or marks an email as spam, a later
grantedfrom your server is ignored, so a sync that sendsgrantedfor everyone can’t undo it. To opt a user in again, sendevidence.atlater than their unsubscribe. The response always shows the stored consent and who set it (source).
To mirror unsubscribes in your own systems, poll GET /v1/consent-events. It lists every consent
change in the project, oldest first. Pass the returned cursor as after next time; when nothing
changed, you get no events and the same cursor back.
curl "https://api.rollout.so/v1/consent-events?after=1042" -H "Authorization: Bearer sk_live_…"Endpoints
Section titled “Endpoints”| Method and path | Description |
|---|---|
POST /v1/subjects |
Create or update a user by userId. |
GET /v1/subjects/{id} |
The stored user. |
DELETE /v1/subjects/{id} |
Forget the user and their read state. |
GET /v1/subjects/{id}/feed |
The user’s feed (limit, cursor, unread, view). |
GET /v1/subjects/{id}/feed/unread-count |
{ "count": n }. |
GET /v1/subjects/{id}/feed/highlight |
The highlight to tease, or null. |
GET /v1/subjects/{id}/announcements/{announcementId} |
One announcement in full. |
POST /v1/subjects/{id}/announcements/{announcementId}/read |
Mark one announcement read. |
POST /v1/subjects/{id}/announcements/{announcementId}/highlight/dismiss |
Close its highlight teaser (it stays unread). |
POST /v1/subjects/{id}/feed/read-all |
Mark everything read. |
GET /v1/consent-events |
Consent changes (after, limit). |
The feed has the same shape as in the browser: announcements, unreadCount and nextCursor.
Pass nextCursor as cursor to get the next page; limit is 1–50 (default 20). Targeting uses
the user’s stored orgId and attrs. See Lists and teasers
for unread, view=summary and the highlight.
Reference
Section titled “Reference”Every endpoint, with request and response schemas, is in the
REST API reference. The API’s base URL is https://api.rollout.so.