observed by real signal

Real Signal — public API

Real Signal publishes its substrate. Every endpoint below returns aggregate-only output, never per-individual data. All are readable without authentication and freely citable by journalists, urban planners, AI assistants, or any system that needs a verifiable read of Singapore neighbourhood commercial rhythm.

Doctrine: numbers do the work; the silence (the agent's choice not to surface) is also published; every forecast is cryptographically sealed at write time and revealed at the predicted hour with the actual outcome.

Substrate

The raw observational layer the agent reads from. Aggregate, pocket-level, never per-individual.

`GET /api/pocket-live`

params: pocket=cluny

Current pocket snapshot: latest atmosphere reading, last 5 narrations, last 5 revealed predictions, last 5 sustainability events, 24h resonance time-series.

example response

{ "pocket": {...}, "atmosphere_latest": {...}, "narrations_recent": [...], "resonance": { "score": 0.72, "should_surface": true, "layers": {...} }, "resonance_history_24h": [...] }

try it: curl -s "https://real-signal.ai/api/pocket-live?pocket=cluny"

`GET /api/observed-patterns`

params: id=<outlet_id>

Inferred patterns for an outlet — quiet windows, rain sensitivity, DNA descriptor, hours overlap. Each pattern carries confidence + basis.

example response

{ "outlet_id": "...", "patterns": [ { "kind": "quiet_window", "text": "Quieter rhythm observed in your building between 14:00–17:00 SGT...", "confidence": "medium", "basis": "84 atmosphere readings over the last 14 days" }, ... ] }

try it: curl -s "https://real-signal.ai/api/observed-patterns?id="

`GET /api/intent`

params: pocket=cluny&slug=quiet-now

Intent-shaped substrate for one of 72 (pocket × intent) combinations. Slugs: quiet-now, rain-friendly, late-lunch, work-friendly.

example response

{ "pocket": {...}, "intent": {...}, "match_ratio": 0.34, "confidence": "medium", "reasoning": [...], "signal_tier": {...} }

try it: curl -s "https://real-signal.ai/api/intent?pocket=cluny&slug=quiet-now"

Decisions

The brain — what the agent thinks about this moment, and what it would propose if asked.

`GET /api/resonance`

params: pocket=cluny[&outlet=<id>][&tier=experience]

The 7-layer resonance score: time × physical × human-energy × merchant-state × attention-density × intent × temporal. Below threshold (0.5) the system stays silent.

example response

{ "resonance": { "score": 0.78, "should_surface": true, "threshold": 0.5, "decay_at": "...", "decay_reason": "...", "layers": { "time": { "score": 0.80, "reasoning": "..." }, ... } } }

try it: curl -s "https://real-signal.ai/api/resonance?pocket=cluny[&outlet=][&tier=experience]"

`GET /api/deal-proposal`

params: outlet=<id>

The agent's current proposal for an outlet (or null when atmosphere tier — the moment doesn't call for a deal).

example response

{ "proposal": { "tier": "experience", "headline": "...", "math": { "regular_price_sgd": 10.5, "proposed_price_sgd": 8.5, "saving_sgd": 2.0 }, "merchant_reason": "...", "consumer_reason": "...", "mutual_benefit": "..." } }

try it: curl -s "https://real-signal.ai/api/deal-proposal?outlet="

`GET /api/composed-narrative`

params: pocket=cluny[&outlet=<id>][&format=narration|push|mastodon|whatsapp|email_para]

Channel-sized narrative line with math embedded inside the observational sentence. Three beats: observation · math · window.

example response

{ "line": "afternoon calm at one cafe in cluny court · pairing at S$8.50 (was S$10.50) · 15:00–17:00 SGT", "tier": "experience" }

try it: curl -s "https://real-signal.ai/api/composed-narrative?pocket=cluny[&outlet=][&format=narration|push|mastodon|whatsapp|email_para]"

Forecasting

Time-locked predictions ledger. Every projection sealed at write time with a SHA-256 hash; revealed at the predicted hour with the actual outcome. Publicly verifiable.

`GET /api/predictions`

params: [pocket=cluny][&since=7d][&revealed=only|pending|both]

Every prediction the platform has sealed, with the actual observation + accuracy score once revealed. Recompute the SHA-256 yourself to verify the platform committed before the predicted hour.

example response

{ "predictions": [ { "generator": "pocket_projection_60m", "sealed_at": "...", "reveal_at": "...", "prediction_payload": {...}, "actual_observation": {...}, "accuracy_score": 1.0, "payload_hash": "sha256:..." } ], "stats": { "by_generator": {...}, "mean_accuracy": 0.71 } }

try it: curl -s "https://real-signal.ai/api/predictions?[pocket=cluny][&since=7d][&revealed=only|pending|both]"

Publication & dashboards

What the agent surfaces publicly — including the silence.

`GET /api/silence`

params: window=7d|14d|30d

Count of every signal the agent chose NOT to send, plus an attention-minutes-preserved estimate. The doctrine's silence-as-infrastructure made measurable.

example response

{ "total_silenced": 847, "attention_minutes_preserved": 1694, "per_pocket": [...], "per_reason": [ { "reason": "resonance_low", "count": 583 }, ... ], "daily_counts": [...] }

try it: curl -s "https://real-signal.ai/api/silence?window=7d|14d|30d"

`GET /api/sustainability`

params: [pocket=cluny][&merchant=<uuid>][&window=7d|30d|90d|all][&format=narrative]

Layer 4 ledger: physical magnitude AND SGD valuation for every event where the agent kept commercial value from being wasted.

example response

{ "totals": { "dollar_value_recovered": 142, "waste_avoided_units": 87, "idle_reclaimed_hours": 4, "purposeful_trips": 11 }, "per_pocket": [...] }

try it: curl -s "https://real-signal.ai/api/sustainability?[pocket=cluny][&merchant=][&window=7d|30d|90d|all][&format=narrative]"

`GET /api/notebook`

params: month=YYYY-MM[&pocket=cluny]

Monthly aggregate substrate for the agent's notebook archive: atmosphere readings, prediction stats, sustainability dollar value, narrations rendered.

example response

{ "month": "2026-05", "atmosphere": { "total_readings": 324, "anomalies": 7 }, "predictions": { "total_sealed": 36, "revealed": 12, "mean_accuracy": 0.71 }, "sustainability": { "total_events": 48, "dollar_value_total": 1842.5 } }

try it: curl -s "https://real-signal.ai/api/notebook?month=YYYY-MM[&pocket=cluny]"

`GET /api/changelog`

params: days=14

Daily history of agent state — one row per UTC day. Aggregated on demand from existing substrate; same numbers reproducible from the other endpoints in this category.

example response

{ "entries": [ { "date": "2026-05-18", "atmosphere_readings": 96, "narrations_surfaced": 12, "notifications_deferred": 187, "surfaced_ratio": 6.0, "predictions_sealed": 54, "predictions_revealed": 36, "mean_accuracy": 0.71, "sustainability_sgd": 142, "top_pocket": { "pocket_id": "cluny", "count": 28 } } ] }

try it: curl -s "https://real-signal.ai/api/changelog?days=14"

`GET /api/stream`

params: limit=50&since=24h[&pocket=cluny]

Per-event chronological feed across narrations, revealed predictions, and sustainability ledger. Reverse-chronological, capped at 200, since-windowed (1h, 6h, 24h, 7d, all).

example response

{ "events": [ { "type": "narration", "timestamp": "2026-05-19T10:00:00Z", "pocket_id": "cluny", "tier": "experience", "body": "afternoon calm at one cafe..." }, { "type": "prediction", "timestamp": "2026-05-19T09:00:00Z", "pocket_id": "cluny", "generator": "pocket_projection_60m", "expected": "busy", "actual": "busy", "accuracy": 1.0 }, { "type": "sustainability", "timestamp": "2026-05-19T08:00:00Z", "pocket_id": "cluny", "kind": "waste_avoided", "value": 3, "dollar_value": 10.5 } ] }

try it: curl -s "https://real-signal.ai/api/stream?limit=50&since=24h[&pocket=cluny]"

Embeddable widgets

Iframe-friendly mini-views any merchant can drop on their own website. No app download, no API key, no cross-origin restrictions.

`GET /widget/pocket/:pocket`

Compact iframe-friendly view of one pocket: current atmosphere state, decay reason, resonance speaking/quiet badge, "powered by Real Signal" link. ~2 KB; no external JS; sized for 320–480 px wide embeds.

example response

<!DOCTYPE html><html><body><div class="widget">...</div></body></html>

try it: curl -s "https://real-signal.ai/widget/pocket/:pocket"

System health & discoverability

Public probes for platform health + indexing.

`GET /api/heartbeat`

9-row health scorecard: env_snapshots freshness, agent worker, gate pass rate, takedown SLA, human reviews backlog, inbound MX, LTA signals, migrations applied, stale crons.

example response

{ "status": "green", "checks": [ { "name": "env_snapshots", "status": "green", "value": "fresh: 4 min", "hint": "..." }, ... ] }

try it: curl -s "https://real-signal.ai/api/heartbeat"

`GET /api/migration-status`

Which schema migrations have been applied vs missing. Heartbeat-feeding probe.

example response

{ "all_applied": true, "missing_count": 0, "checks": [ { "key": "predictions_ledger", "applied": true }, ... ] }

try it: curl -s "https://real-signal.ai/api/migration-status"

`GET /api/version`

Build version (the deployed git SHA). The SPA auto-refresh hook reads this to detect new deploys.

example response

{ "version": "f41822f", "deployed_at": "..." }

try it: curl -s "https://real-signal.ai/api/version"

`GET /api/health`

Simple liveness probe.

example response

{ "ok": true }

try it: curl -s "https://real-signal.ai/api/health"

`GET /sitemap.xml`

XML sitemap of every indexable surface — ~140 URLs (static + per-pocket + per-intent + per-outlet). lastmod per surface drives crawler revisits.

example response

<urlset xmlns="..."><url><loc>https://real-signal.ai/intent/cluny/quiet-now</loc><lastmod>2026-05-19</lastmod><changefreq>daily</changefreq><priority>0.6</priority></url>...</urlset>

try it: curl -s "https://real-signal.ai/sitemap.xml"

What's NOT here

Endpoints that require authentication — admin / ops dashboards, merchant proposal publishing — are deliberately not documented here. Their shapes can change without notice; only authenticated callers should depend on them. Public endpoints above are stable.