Skip to content
rolloutrolloutrollout docs

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 → API keys. It’s shown once; store it like a password and never ship it to a browser. Send it as a bearer token:

Terminal window
curl https://api.rollout.so/v1/subjects/sbj_… \
  -H "Authorization: Bearer sk_live_…"

Secret keys only work on /v1/subjects routes, and publishable keys only on the browser feed, so a leaked publishable key can’t act for arbitrary users.

Users

Section titled “Users”

  1. Create or update the user by your own id. POST /v1/subjects is idempotent on userId: it returns 201 for a new user and 200 otherwise. 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
    userId Required. Your id for the user, any string up to 256 characters.
    orgId The user’s organization or account; null clears it.
    createdAt When the user signed up; older announcements count as read. null clears it.
    attrs Custom attributes for targeting. Replaces the stored attributes, max 16 KB.

  2. Keep the returned id. It looks like sbj_… 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.

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).
GET /v1/subjects/{id}/feed/unread-count { "count": n }.
POST /v1/subjects/{id}/announcements/{announcementId}/read Mark one announcement read.
POST /v1/subjects/{id}/feed/read-all Mark everything read.

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.

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.