Custom Streams

Custom streams let authors publish one stream that can deliver different subsets of posts to different customers — based on custom targets the customer selects and purchases.

When an author submits a post to a custom stream, they include a customTarget. Customers then configure their targets for that stream. Posts are delivered only if the customTarget matches one of the customer’s selected targets.

Regular vs Custom Streams

• Regular stream: every follower receives every post.

• Custom stream: each follower only receives posts matching the customTarget values they have purchased and set.

Key Concepts

• Stream ID: unique identifier for the stream (ULID).

• Custom targets: the list of tags you, as a customer, purchase from the author and configure for a stream (e.g., ["US", "EU"] or ["BTC", "ETH"]).

• Post customTarget: a string provided by the author when publishing to a custom stream.

• Purchase limits: authors may define how many targets a customer can buy.

• No targets = no posts: if you don’t select targets, you won’t receive any posts from that stream.

Step-by-Step: Customer Setup

1. Follow and inspect the stream

• You must follow the stream to receive posts.

• View the stream info in app ui or using the REST api. GET /v1/streams/{streamId}

2. Purchase and set your targets

• Authors may offer many targets; your purchase defines how many you can use.

• UI: select your targets directly on the stream page.

• REST API POST /v1/streams/{streamId}/custom-targets

  Notes:

  • This call replaces your existing list of targets.

  • Targets are case-sensitive.

  • Invalid targets will reject the whole call

3. Receive posts

Realtime (recommended) via WebSocket on-stream-post

• Connect to wss://api.synoptic.com/v1/ws?apiKey=YOUR_READER_KEY.

• Subscribe to stream events using on-stream-post.

• Posts will include customTarget. You’ll only get those that match your configured list.

Polling (optional) via REST GET /v1/streams/{streamId}/posts

• GET /v1/streams/{streamId}/posts?limit=50

• Requires Reader API key and that you follow the stream.

• Results are filtered by your current custom targets.

4. Update targets anytime

• Re-run step 2 to change your target list.

• The new list replaces the old one.

Note: The entered targets are lost when you unfollow the stream.

FAQ

• What if I don’t set any targets? You’ll receive no posts.

• Are targets case-sensitive? Yes.

• Can I use wildcards? No, matches must be exact.

• How many targets can I set? Depends on your purchase limit; defined by the author. See stream card for details.