API Reference

This API is in active development. Some functions may not be stable yet, and the interface is subject to change.

Endpoint

wss://api.synoptic.com/v1/ws

Authentication

Generate your READER api key in settings -> API & Keys

Query Params

wss://api.synoptic.com/v1/ws?apiKey=<YOUR_KEY>

Header

wss://api.synoptic.com/v1/ws
--header "x-api-key: <YOUR_KEY>"

Commands

A command is called by sending a message with the following format

{
  "event": "<COMMAND>",
  "data": {
    ... COMMAND ARGUMENTS
  }
}

Alternatively, you can invoke the command directly with the connection URL, e.g.

wss://api.synoptic.com/v1/ws/on-stream-post?apiKey=<APIKEY>&streamIds=<...>&lastPosts=<...>

on-stream-post

Subscribe to receive stream posts.

Arguments

• streamIds: string (optional) — Comma-separated list of stream IDs. Only posts from these streams will be returned if specified.

  • If omitted → defaults to all streams the user is subscribed to.

  • If provided but empty → also defaults to all streams the user is subscribed to.

  • If provided with values → only posts from the specified streams are returned.

• lastPosts: number (optional) - On connection, receive lastPosts recent posts from each stream you are connected to. Default: 0.

on-stream-post-tree

Receive posts in tree terminal format. See Tree Terminal

Arguments

• streamIds: string (optional) — Comma-separated list of stream IDs. Only posts from these streams will be returned if specified.

  • If omitted → defaults to all streams the user is subscribed to.

  • If provided but empty → also defaults to all streams the user is subscribed to.

  • If provided with values → only posts from the specified streams are returned.

• lastPosts: number (optional) - On connection, receive lastPosts recent posts from each stream you are connected to. Default: 0.

add-stream-post

Publish a post to your stream.

Arguments

• streamId: string - ID of your stream. You must use the key assigned to this stream.

• content: string - Text or markdown content of your post.

• contentType: "rawtext" | "markdown" - specify whether to parse your text as markdown.

• releaseAt: string (optional) - ISO8601 formatted date. Specify when your post content should become available. The post will appear on synoptic immediately but the content will be hidden.

• customTarget: string (optional) - for custom streams only. Specify which custom target the post is associated with.

• idempotencyKey: string (optional) - Posts with the same idempotencyKey will be deduplicated. Synoptic will deduplicate posts submitted within seconds or minutes of each other; however, no deduplication guarantees are provided for longer periods.