Modernity API

Real-time streaming access to 18+ live data sources. Connect via SSE for continuous streaming, or query the knowledge base for structured responses.

Endpoints

Streaming: https://modernity-production.up.railway.app/v1/live
API: https://api.modernity.live/v1

Get Your API Key

Generate an API key instantly — no signup required.

Generate API Key

Enter your email to get an API key.

Quick Start

Make your first API call:

Shell

curl -X POST https://api.modernity.live/v1/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topic": "AI news", "limit": 5}'

Live Stream (SSE)

Connect to the real-time firehose via Server-Sent Events. All 18+ sources stream continuously.

Endpoint

GET https://modernity-production.up.railway.app/v1/live

JavaScript Example

JavaScript

const eventSource = new EventSource(
    'https://modernity-production.up.railway.app/v1/live'
);

eventSource.addEventListener('item', (e) => {
    const data = JSON.parse(e.data);
    console.log(data.source, data.message);
});

eventSource.addEventListener('connected', (e) => {
    console.log('Connected to stream');
});

Python SSE Example

Python

import requests

url = "https://modernity-production.up.railway.app/v1/live"
with requests.get(url, stream=True) as r:
    for line in r.iter_lines():
        if line:
            print(line.decode())

SSE Event Types

Event	Description
`connected`	Initial connection confirmation
`item`	Data item from any source
`ping`	Keepalive ping (every 15s)

Item Payload

JSON

{
  "source": "bluesky",
  "message": "Post content here...",
  "timestamp": 1738678425,
  "metadata": { ... }
}

Query Endpoint

Query the knowledge base with natural language.

Python Example

Python

import requests

response = requests.post(
    "https://api.modernity.live/v1/query",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "topic": "AI developments",
        "limit": 10
    }
)

data = response.json()
print(f"Latency: {data['latency_ms']}ms")

Query Endpoint

HTTP

POST https://api.modernity.live/v1/query

Parameters

Parameter	Type	Required	Description
`topic`	string	Yes	Natural language query
`timeframe`	string	No	`60s`, `5m`, `1h`, `24h`. Default: `60s`
`sources`	array	No	Filter by specific sources
`limit`	integer	No	Max results (1-100). Default: 10

Response Format

JSON

{
  "id": "qry_10e4030bbc7f2490",
  "latency_ms": 319,
  "freshness_seconds": 42,
  "sources_queried": 3,
  "results": [
    {
      "title": "AI News Wrap-Up...",
      "source": "bluesky",
      "age_seconds": 42,
      "relevance": 0.9189,
      "summary": "..."
    }
  ]
}

Error Handling

Code	Description
`400`	Invalid request parameters
`401`	Invalid or missing API key
`429`	Rate limit exceeded
`500`	Internal server error

Python SDK

Shell

pip install modernity

Python

from modernity import Modernity

client = Modernity(api_key="your-api-key")
response = client.query(topic="bitcoin price")

Node.js SDK

Shell

npm install @modernity/sdk

TypeScript

import { Modernity } from '@modernity/sdk';

const client = new Modernity({ apiKey: process.env.MODERNITY_API_KEY });
const response = await client.query({ topic: 'NVDA earnings' });

cURL Examples

Shell

# Query
curl -X POST https://api.modernity.live/v1/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topic": "bitcoin price", "limit": 5}'

# Generate API Key
curl -X POST https://api.modernity.live/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

# List Sources
curl https://api.modernity.live/v1/sources

Available Sources

18+ data sources streaming live data continuously.

Live Streaming

Source	Category	Description
`bluesky`	Social	Bluesky Jetstream firehose
`mastodon`	Social	Mastodon federated public stream
`wikimedia`	News	Wikipedia recent changes
`mempool`	Crypto	Bitcoin mempool blocks

Frequent Polling (10-60s)

Source	Category	Description
`opensky`	Aviation	Live aircraft positions
`coingecko`	Crypto	Top cryptocurrency prices
`kalshi`	Finance	Prediction market prices
`github`	Tech	Public GitHub events
`hackernews`	Tech	Hacker News stories
`drand`	Crypto	Randomness beacon
`iss`	Space	ISS location tracking
`wttr`	Geo	Global city weather (80+ cities)

Moderate Polling (1-15 min)

Source	Category	Description
`gdelt`	News	Global news in 65 languages
`usgs`	Geo	Earthquake alerts (M2.5+)
`cisa`	Security	CISA security advisories
`urlhaus`	Security	Malware URL database

Rate Limits

Free tier: 1,000 queries/month
Pro tier: 50,000 queries/month
Contact us for higher limits.