Modernity API

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}'

GET https://api.modernity.live/v1/live?api_key=YOUR_API_KEY

const eventSource = new EventSource(
    'https://api.modernity.live/v1/live?api_key=YOUR_API_KEY'
);

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');
});

import requests

url = "https://api.modernity.live/v1/live?api_key=YOUR_API_KEY"
with requests.get(url, stream=True) as r:
    for line in r.iter_lines():
        if line:
            print(line.decode())

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

GET /v1/recent?api_key=YOUR_KEY&limit=100&offset=0

import requests

# Page 1: newest 100 messages
r1 = requests.get("https://api.modernity.live/v1/recent", params={
    "api_key": API_KEY, "limit": 100, "offset": 0
}).json()

# Page 2: next 100
r2 = requests.get("https://api.modernity.live/v1/recent", params={
    "api_key": API_KEY, "limit": 100, "offset": 100
}).json()

print(f"Page 1: {r1['count']} msgs, has_more: {r1['has_more']}")
print(f"Page 2: {r2['count']} msgs, total in buffer: {r2['total']}")

# Get all crypto news from the last 5 minutes
FIVE_MIN_AGO=$(date -v-5M +%s)  # macOS
curl "https://api.modernity.live/v1/recent?api_key=YOUR_KEY&category=crypto&since=$FIVE_MIN_AGO&limit=200"

{
  "count": 100,
  "total": 12847,
  "offset": 0,
  "limit": 100,
  "has_more": true,
  "messages": [
    {
      "source": "bluesky",
      "schema": "social",
      "doc_id": "bsky_abc123",
      "title": "Post title...",
      "message": "Post content...",
      "timestamp": 1738678425,
      "category": "social"
    }
  ]
}

GET /v1/snapshot?api_key=YOUR_KEY

{
  "buffer_capacity": 20000,
  "buffer_used": 14832,
  "oldest_timestamp": 1738670000,
  "newest_timestamp": 1738678425,
  "time_span_seconds": 8425,
  "sources": [
    { "source": "bluesky", "count": 4200, "latest_timestamp": 1738678420 },
    { "source": "coingecko", "count": 980, "latest_timestamp": 1738678415 }
  ],
  "categories": [
    { "category": "social", "count": 5100 },
    { "category": "crypto", "count": 2400 }
  ],
  "messages_per_second": 18.4,
  "uptime_seconds": 86400
}

GET /v1/counts?api_key=YOUR_KEY&group_by=source

{
  "group_by": "both",
  "total": 14832,
  "counts": {
    "bluesky": { "social": 4200 },
    "coingecko": { "crypto": 980 },
    "currents": { "news": 1420, "tech": 630 }
  }
}

GET /v1/sources/live?api_key=YOUR_KEY

{
  "sources": [
    { "source": "bluesky", "count": 4200, "latest_timestamp": 1738678420 }
  ],
  "health": {
    "bluesky": { "total": 128400, "recent_60s": 42, "rate_per_sec": 0.7 }
  }
}

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")

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

{
  "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": "..."
    }
  ]
}

{
  "mcpServers": {
    "modernity": {
      "command": "npx",
      "args": ["-y", "modernity-mcp"],
      "env": {
        "MODERNITY_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "modernity": {
      "command": "npx",
      "args": ["-y", "modernity-mcp"],
      "env": {
        "MODERNITY_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

npx -y modernity-mcp --key=YOUR_API_KEY --test

Success! API is online and your key is valid.

# Get a pulse on the world
"What's going on with the world?"
"What are people talking about online right now?"
"Give me a snapshot of what's happening today"

# Dive into specific topics
"Any earthquakes in the last hour?"
"What's happening in AI right now?"
"Get the latest crypto prices"
"What are the top Hacker News stories?"
"Are there any severe weather alerts in the US?"

# Research and analysis
"Analyze the topic 'semiconductor supply chain'"
"What's the latest research on LLMs from arXiv?"
"Search for SEC filings related to AI companies"

# Build with Modernity
"Help me integrate Modernity into my Next.js app"
"Generate Python code to monitor crypto prices"
"Show me the API docs for the /v1/query endpoint"
"What error codes does the Modernity API return?"

pip install modernity

from modernity import Modernity

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

npm install @modernity/sdk

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

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

# Recent messages (paginated, newest-first)
curl "https://api.modernity.live/v1/recent?api_key=YOUR_KEY&limit=100&offset=0"

# Filter by source + time range (last 10 min)
curl "https://api.modernity.live/v1/recent?api_key=YOUR_KEY&source=bluesky&since=$(date -v-10M +%s)"

# Buffer snapshot (no message bodies)
curl "https://api.modernity.live/v1/snapshot?api_key=YOUR_KEY"

# Message counts grouped by source
curl "https://api.modernity.live/v1/counts?api_key=YOUR_KEY&group_by=source"

# Live source health
curl "https://api.modernity.live/v1/sources/live?api_key=YOUR_KEY"

# Query (semantic search)
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": "[email protected]"}'