SignalFlow API

Real-time cross-platform signal intelligence across Reddit, HackerNews, Bluesky and YouTube. The API surfaces trending topics, sentiment, velocity and LLM-generated intelligence — automatically.

Base URL

https://signalflo.xyz/api/v1/

Authentication

All endpoints require an API key. Get yours at signalflo.xyz — click "Get API Key". Pass your key as a Token in the Authorization header.

http header

Authorization: Token your_api_key_here

Get your key at signalflo.xyz — click "Get API Key". Same email always returns the same key.

Quick Start

Get trending topics with intelligence in under a minute.

cURL

Python

JavaScript

Node.js

bash

# get trending topics
TOKEN="your_token_here"
curl "https://signalflo.xyz/api/v1/trending/?window=60&limit=10" \
  -H "Authorization: Token $TOKEN"

# topic intelligence
curl "https://signalflo.xyz/api/v1/pulse/?topic=iran" \
  -H "Authorization: Token $TOKEN"

python

import requests

BASE    = "https://signalflo.xyz/api/v1"
TOKEN   = "your_token_here"
HEADERS = {"Authorization": f"Token {TOKEN}"}

# trending topics
data = requests.get(
    f"{BASE}/trending/",
    params={"window": 60, "limit": 10},
    headers=HEADERS
).json()

for t in data["topics"]:
    print(t["topic"], t["trend_score"])

# topic intelligence
pulse = requests.get(
    f"{BASE}/pulse/",
    params={"topic": "iran"},
    headers=HEADERS
).json()

intel = pulse.get("intelligence") or {}
print(intel.get("summary"))
print(intel.get("divergence_explanation"))

javascript

const BASE    = "https://signalflo.xyz/api/v1";
const TOKEN   = "your_token_here";
const HEADERS = {"Authorization": `Token ${TOKEN}`};

// trending topics
const {topics} = await fetch(
  `${BASE}/trending/?window=60&limit=10`,
  {headers: HEADERS}
).then(r => r.json());

topics.forEach(t => console.log(t.topic, t.trend_score));

// topic intelligence
const pulse = await fetch(
  `${BASE}/pulse/?topic=iran`,
  {headers: HEADERS}
).then(r => r.json());

const {intelligence} = pulse;
if (intelligence) {
  console.log(intelligence.summary);
  console.log(intelligence.dominant_narrative);
}

node.js

// Node 18+ has built-in fetch. Older: npm install node-fetch
const BASE    = "https://signalflo.xyz/api/v1";
const TOKEN   = "your_token_here";
const HEADERS = {"Authorization": `Token ${TOKEN}`};

const {topics} = await fetch(
  `${BASE}/trending/?window=60&limit=10`,
  {headers: HEADERS}
).then(r => r.json());

topics.forEach(t => console.log(t.topic, t.trend_score));

/trending/

GET /api/v1/trending/

Returns trending topics ranked by signal velocity and cross-platform spread. Cross-platform topics rank higher than single-platform ones.

Parameters

Parameter	Type	Description
window	integer	optional Time window in minutes. Default: 60. Try 240 for more results.
platform	string	optional Filter by: all \| reddit \| hackernews \| bluesky \| youtube. Default: all.
limit	integer	optional Max topics returned. 1–50. Default: 20.

Example

bash

Response Fields

topics[].topicstringTopic name extracted by spaCy NER

topics[].trend_scorefloatComposite score: velocity × platform spread × sentiment weight

topics[].signal_countintegerSignals mentioning this topic in the window

topics[].platform_countintegerDistinct platforms covering this topic

topics[].platformsarrayList of platform names

topics[].avg_sentimentfloatAverage VADER compound score (-1 to +1)

topics[].avg_velocityfloatAverage score change per second

topics[].cross_platformbooleanTrue if topic appears on 2+ platforms

/pulse/

GET /api/v1/pulse/?topic=

Deep intelligence for a single topic. Returns per-platform sentiment breakdown, divergence score, momentum, and LLM-generated intelligence including summary, dominant narrative, emerging counter-angle and platform divergence explanation.

Most Valuable Endpoint

The intelligence block contains LLM-generated analysis updated every 15 minutes — not available anywhere else.

Parameters

Parameter	Type	Description
topic	string	required Topic name. Use topics from /trending/ for best results.
window	integer	optional Time window in minutes. Default: 60.

Example

bash

curl "https://signalflo.xyz/api/v1/pulse/?topic=iran&window=60" \
  -H "Authorization: Token YOUR_KEY"

Response Fields

overall_sentimentfloatMean sentiment across all platforms (-1 to +1)

overall_momentumstringrising | stable | falling

signal_countintegerTotal signals in the window

platformsobjectPer-platform breakdown with avg_sentiment, signal_count, momentum, top_signal

divergence.scorefloatMax sentiment difference between platforms (0 to 2)

divergence.alertbooleanTrue if score ≥ 0.3 — platforms significantly disagree

intelligenceobjectLLM-generated analysis. See Intelligence Block below.

/signals/

GET /api/v1/signals/

Paginated raw signal feed across all platforms ordered by ingestion time. Each signal is a post, comment or story from one of the 4 platforms.

Parameters

Parameter	Type	Description
platform	string	optional Filter by platform.
limit	integer	optional Page size. Default: 20, max: 100.
ordering	string	optional Use -first_seen_at for newest first.

Example

bash

curl "https://signalflo.xyz/api/v1/signals/?limit=20&ordering=-first_seen_at" \
  -H "Authorization: Token YOUR_KEY"

/compare/

GET /api/v1/compare/

Cross-platform divergence events — moments when platforms covered the same topic with significantly different sentiment. Useful for detecting platform-specific bias or information asymmetry.

Example

bash

curl "https://signalflo.xyz/api/v1/compare/" \
  -H "Authorization: Token YOUR_KEY"

/stats/

GET /api/v1/stats/totals/

All-time and last-24h signal counts per platform.

Example

bash

curl "https://signalflo.xyz/api/v1/stats/totals/" \
  -H "Authorization: Token YOUR_KEY"

Response

json

{
  "all_time": {
    "total":      1721135,
    "reddit":     150937,
    "hackernews": 11419,
    "youtube":    84164,
    "bluesky":    1474597
  },
  "last_24h": {
    "total":      191080,
    "reddit":     17569,
    "hackernews": 988,
    "youtube":    9779,
    "bluesky":    162744
  }
}

Intelligence Block

Every /pulse/ response includes an intelligence object generated by an LLM every 15 minutes. It reads the top signals for the topic across all platforms and extracts structured analysis.

How it works

The summariser runs outside the hot path — ingestion is never delayed. It reads from the DB every 15 minutes, calls the LLM on trending topics, and writes results back. The API joins the latest summary on each request at zero latency cost.

Intelligence Fields

intelligence.summarystring3-sentence narrative: what people are saying, what's driving volume, overall mood.

intelligence.dominant_narrativestring5–8 words: the main thing most people are saying.

intelligence.emerging_anglestring5–8 words: minority view or counter-narrative. Null if none.

intelligence.divergence_explanationstring1 sentence explaining why platforms differ. Null if they agree.

intelligence.generated_atdatetimeWhen this summary was generated. Max age ~30 min for active topics.

intelligence.modelstringLLM model used to generate this summary.

Example Response

json

{
  "intelligence": {
    "summary": "People are discussing US attacks on Iran's Kharg Island oil infrastructure. The volume is driven by breaking news coverage across all 4 platforms. Overall mood is strongly negative.",
    "dominant_narrative": "US strikes on Kharg Island cause oil supply fears",
    "emerging_angle": "Diplomatic back-channel negotiations still active",
    "divergence_explanation": "Bluesky users provide geopolitical context while Reddit primarily shares news reactions.",
    "generated_at": "2026-03-16T10:31:23Z",
    "model": "llama-3.1-8b-instant"
  }
}

Errors

Status	Meaning	Description
200	OK	Request succeeded.
400	Bad Request	Missing required parameter.
401	Unauthorized	Invalid or missing API key.
429	Too Many Requests	Rate limit exceeded.
500	Server Error	Something went wrong. Try again in a few seconds.