Live data + tokens

A streamboard spec authored via MCP is static structure. The values inside KPI tiles, charts, and tables come from a separate state envelope you push from your own code. This guide walks through tokens, the push surface, and the pull surface.

Mint a token

1. Open a streamboard you own at https://usestreamboard.com/s/<id>
2. Click the settings gear → Tokens, or go to /app/s/<id>/tokens
3. Click Create token, optionally label it (“github-actions”, “monitor”), copy the secret — it’s shown once and never again

Token format: sb_d_<id>_<secret>. The id segment is the streamboardId; the SDK parses it automatically.

A token scopes to one streamboard. Mint one per worker / pipeline; revoke individually.

Push state

import { Streamboard } from "@streamboard/sdk"

const board = new Streamboard({ token: process.env.STREAMBOARD_TOKEN! })

await board.push({
  kpis: { mrr: { value: "$48k", delta: "+4%", trend: "up" } },
})

Or via the CLI:

echo '{"kpis":{"mrr":{"value":"$48k"}}}' | streamboard streamboards push <id>

Or raw HTTP:

curl -X POST https://usestreamboard.com/api/data/v1/streamboards/<id> \
  -H "Authorization: Bearer $STREAMBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state": {"kpis": {"mrr": {"value": "$48k"}}}}'

Last-write-wins. Each push replaces the entire state envelope on the server. 64 KB body cap.

Pull state

Read the current envelope back — useful for diffing in a downstream worker, or for monitoring scripts that alert on staleness.

const { state, version, updatedAt } = await board.pull()
//   state:      { kpis: { mrr: { value: "$48k" } } }   ← {} if never pushed
//   version:    7                                        ← latest spec version
//   updatedAt:  1747235600123                            ← null if never pushed

CLI:

streamboard streamboards pull <id> --state   # prints just the envelope JSON

Rate limits

Limit	Scope	Default
Per-token	one token id	60 / minute
Per-streamboard	all tokens on a board	600 / minute
Per-organisation (writes only)	all tokens in an org	6,000 / minute

The SDK retries on 429 + 5xx with exponential jitter (3 attempts by default). Override via the retries option, or pass 0 to disable.

Security posture

• Secrets are SHA-256 hashed before storage. The raw secret leaves your control once after minting.
• Token authorizes both POST (write) and GET (read) — if a token can update state, it can read it back.
• Revoking a token deletes the row; subsequent requests get a 401 immediately.
• Read-side rate-limits are tighter than write-side because reads are idempotent and cheaper to retry.