API reference

Authentication

All feed access uses an API key. Generate one in your dashboard (up to 5 active). Keys are shown once — store them securely. A key streams and backfills every feed your account is subscribed to.

Authorization: Bearer nf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

For WebSocket, pass the key in the Authorization header, or as a ?key= query parameter when a header isn't available.

REST — recent history

Fetch recent items for a feed, newest first.

GET /v1/feeds/{feed}/items?limit=100

curl "https://feeds.247terminal.com/v1/feeds/headlines/items?limit=100" \
  -H "Authorization: Bearer $KEY"

Query parameters

Response

{
  "feed": "headlines",
  "items": [
    {
      "id": 48213,
      "feeds": ["headlines"],
      "kind": "wsj",
      "headline": "EXCLUSIVE: US WEIGHS NEW EXPORT CURBS ON AI CHIPS",
      "category": "ai",
      "time": 1753009999000,
      "source_id": "a1f2..."
    }
  ],
  "next_cursor": 48120,
  "next_since_id": null
}

WebSocket — realtime

Open one connection, subscribe to the feeds you want, and receive every item the moment it's detected.

wss://feeds.247terminal.com/v1/stream

wscat -c "wss://feeds.247terminal.com/v1/stream" \
  -H "Authorization: Bearer $KEY"

# on connect the server sends:
{"type": "hello", "entitled": ["truth-social", "headlines", "macro"]}

# subscribe to a subset (or all) of your entitled feeds:
> {"subscribe": ["truth-social", "headlines"]}
{"type": "subscribed", "feeds": ["truth-social", "headlines"]}

# then events arrive as they happen:
{"id": 48214, "feeds": ["truth-social"], "type": "truth_post",
 "handle": "realDonaldTrump", "body": "...", "time": 1753009999500}

Message types

The server pings every 30s; respond to pings (most clients do automatically) or the connection is closed. Exceeding 1MB of unread buffer drops the connection as a slow consumer.

Gap-free reconnect

Every item — over WebSocket and REST — carries the same monotonic id. To reconnect without gaps or duplicates, subscribe before you backfill and page the REST backfill to completion:

// 1. reconnect, attach your message handler, send {"subscribe": [...]}
// 2. WAIT for the {"type":"subscribed"} ack, buffering every live event that arrives
// 3. backfill from the last id you processed, following next_since_id until it is null:
GET /v1/feeds/headlines/items?since_id=48214&limit=500   // → next_since_id: 48714
GET /v1/feeds/headlines/items?since_id=48714&limit=500   // → next_since_id: null (done)
// 4. process the backfill, then drain the live buffer, skipping any id already seen

Waiting for the subscribed ack guarantees no live event is dropped during subscription setup; paging until next_since_id is null covers outages longer than one page.

Feeds & payloads

Every event has id, feeds (an array — items can belong to more than one), time (epoch ms), and source_id. The remaining fields depend on the feed:

Errors & limits

Revoking a key or cancelling a subscription takes effect within seconds, including on connected WebSockets.