ScreamUp Public & Corporate Aggregate API

ScreamUp transforms anonymous, ephemeral 15-second emotional voice releases into privacy-preserving, civic and regional emotional pulse intelligence. The Public Aggregate API (/v1) exposes real-time H3 hexagonal frustration hotspots without ever storing or exposing consumer identity, raw audio, transcripts, or exact GPS coordinates.

2. Getting Started

All public aggregate endpoints are served over HTTPS from the ScreamUp Cloudflare Worker edge network. Every response includes a correlation header X-Request-ID and strict security headers (Cache-Control: no-store, X-Content-Type-Options: nosniff).

curl -s "https://screamup-api.shared-backend.workers.dev/v1/hotspots?time_window=24h" \
  -H "Accept: application/json"

3. Architecture Concepts

H3 Resolution 7 Hexagonal Indexing

ScreamUp never persists raw latitude or longitude in Cloudflare D1. When a user optionally grants foreground location at the moment of analysis, the Worker maps the coordinate to an H3 resolution 7 index (e.g., 8760a24b3ffffff) covering approximately 5.16 km² and immediately discards the raw coordinates.

Active Rolling Time Windows

Hotspot queries require evaluating events strictly within one of the four supported rolling windows. Historical lifetime events outside the requested window never cause a sparse cell to appear active:

Scream Score vs. Hotspot Intensity

4. Authentication

Layer 1 (Public V1 Aggregate Endpoints): GET /health and GET /v1/hotspots are readable without authentication under standard IP/edge rate limits.

Layer 2 (Corporate Developer Portal — Phase D2 Foundation): B2B research and civic partners authenticate using scoped Bearer API keys:

Authorization: Bearer sk_live_su_4f8b92a1e7c04d3a9b8e112233445566

Corporate API keys are displayed only once at creation, stored exclusively as SHA-256 hashes (key_hash) with a visible prefix (key_prefix), and can be rotated or revoked immediately without affecting anonymous consumer access.

5. Rate Limits

6. Error Catalog & Retry Semantics

All error responses use the canonical ApiError envelope containing code, human-safe message, and request_id. Stack traces, SQL queries, and upstream secrets are never leaked.

7. Public API Reference

{
  "status": "HEALTHY",
  "service": "screamup-api",
  "version": "1.0"
}

{
  "time_window": "24h",
  "time_window_start_ms": 1760467200000,
  "time_window_end_ms": 1760553660000,
  "total_qualifying_cells": 1,
  "hotspots": [
    {
      "h3_index": "8760a24b3ffffff",
      "center": { "latitude": 19.07609, "longitude": 72.877426 },
      "polygon": [
        { "latitude": 19.089112, "longitude": 72.879814 },
        { "latitude": 19.081428, "longitude": 72.891342 },
        { "latitude": 19.068406, "longitude": 72.888954 },
        { "latitude": 19.063068, "longitude": 72.875038 },
        { "latitude": 19.070752, "longitude": 72.86351 },
        { "latitude": 19.083774, "longitude": 72.865898 }
      ],
      "event_count": 6,
      "scream_count": 6,
      "average_frustration": 78,
      "average_intensity": 74,
      "average_confidence": 86,
      "dominant_category": "TRAFFIC_TRANSIT",
      "time_window": "24h",
      "updated_epoch_ms": 1760553120000,
      "hotspot_score": null
    }
  ]
}

8. H3 Hotspots & Emotional Intensity Scale

Each qualifying hotspot object provides its H3 resolution 7 index, centroid coordinate, 6-vertex hexagon boundary polygon, aggregate counts, dominant problem category, and emotional averages.

9. Canonical Data Schemas

Defined in backend/openapi/public-v1.yaml:

• HealthResponse: { status: "HEALTHY", service: "screamup-api", version: "1.0" }
• HotspotListResponse: { time_window, time_window_start_ms, time_window_end_ms, total_qualifying_cells, hotspots: Hotspot[] }
• Hotspot: { h3_index, center: GeoPoint, polygon: GeoPoint[6], event_count (≥5), scream_count (≥5), average_frustration (0..100), average_intensity (0..100), average_confidence (0..100), dominant_category, time_window, updated_epoch_ms, hotspot_score: null }
• ProblemCategoryCode: TRAFFIC_TRANSIT | CIVIC_INFRASTRUCTURE | WORK_CAREER | PUBLIC_SERVICES | ENVIRONMENT_WEATHER | DIGITAL_TECH | GENERAL_VENT | UNCATEGORIZED
• ApiError: { code, message, request_id, error: { code, message, request_id } }

10. Multi-Language Code Examples

curl -X GET "https://screamup-api.shared-backend.workers.dev/v1/hotspots?time_window=24h&min_lat=18.85&max_lat=19.35&min_lng=72.70&max_lng=73.10" \
  -H "Accept: application/json" \
  -H "X-Request-ID: req_client_demo_01"

const url = new URL('https://screamup-api.shared-backend.workers.dev/v1/hotspots');
url.searchParams.set('time_window', '24h');
url.searchParams.set('limit', '100');

const response = await fetch(url.toString(), {
  method: 'GET',
  headers: { 'Accept': 'application/json' },
});
if (!response.ok) {
  const err = await response.json();
  throw new Error(`[${err.code}] ${err.message} (req: ${err.request_id})`);
}
const data = await response.json();
console.log(`Qualifying k>=5 cells: ${data.total_qualifying_cells}`, data.hotspots);

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<Map<String, dynamic>> fetchQualifyingHotspots({String window = '1h'}) async {
  final uri = Uri.parse('https://screamup-api.shared-backend.workers.dev/v1/hotspots')
      .replace(queryParameters: {'time_window': window});
  final response = await http.get(uri, headers: {'Accept': 'application/json'});
  if (response.statusCode != 200) {
    throw Exception('Failed to load hotspots: ${response.statusCode}');
  }
  return jsonDecode(response.body) as Map<String, dynamic>;
}

import requests

resp = requests.get(
    "https://screamup-api.shared-backend.workers.dev/v1/hotspots",
    params={"time_window": "24h", "limit": 100},
    headers={"Accept": "application/json"},
    timeout=10,
)
resp.raise_for_status()
payload = resp.json()
for cell in payload["hotspots"]:
    assert cell["scream_count"] >= 5  # Guaranteed by ScreamUp k-anonymity
    print(cell["h3_index"], cell["average_frustration"], cell["dominant_category"])

11. Privacy & k-Anonymity Guarantee

12. Acceptable Use Policy

Consumers of the ScreamUp Aggregate API must never attempt to de-anonymize, correlate, or combine H3 aggregate hotspot cells with external individual-level datasets to infer the identity or location of any individual person.

13. Versioning Policy

All public endpoints are versioned under /v1/*. Additive non-breaking fields may be introduced in minor releases; any breaking contract change will be published under /v2/* with at least a 90-day deprecation window.

14. Changelog

v1.0.0 (2026-10-16) — Initial OpenAPI 3.1 public release of GET /health, GET /v1/hotspots, and GET /v1/geo/hotspots with H3 resolution 7 and k ≥ 5 privacy enforcement.

15. Live Service Status

16. Support & Future Corporate Developer Portal

ScreamUp's database and Worker foundation include Phase D2 readiness for partner organizations (api_organizations), sandbox/production projects (api_projects), and SHA-256 hashed API keys (api_keys) with scoped access (hotspots:read) and zero billing coupling in V1.