oruk API - examples and reference

Real-world examples for using the oruk live broadcast intelligence API in PHP, Python, JavaScript, TypeScript, Ruby, Go, and curl.

oruk listens to ~200 radio, TV, social, and structured feeds in real time and publishes corroborated news events with stable ids, multi-source verification, location, and confidence scores. The same data powers the live wire at oruk.ai.

• Base URL: https://api.oruk.ai
• Sign up: https://oruk.ai/signup (free, no credit card)
• Generate keys: https://oruk.ai/dashboard
• Live docs: https://oruk.ai/docs
• Status: https://api.oruk.ai/health

Quick start

# Public feed - no key required
curl https://api.oruk.ai/v1/stories/feed?limit=10

# Authed feed with filters
curl -H "X-API-Key: ork_xxxxxxxx" \
  "https://api.oruk.ai/v1/stories?category=conflict&min_impact=7&limit=20"

That's the whole API in two requests. Everything below is variations on this theme.

Authentication

Pass your API key on every authed request. Three accepted formats:

Public endpoints (no key required, no quota counted): GET /health, GET /v1/health, GET /v1/stories/feed.

Everything else under /v1/* needs a key. Get one at https://oruk.ai/dashboard.

Endpoints at a glance

Query parameters for /v1/stories

Story shape

Every story payload - from /v1/stories, /v1/stories/feed, /v1/stories/{id}, or the SSE stream - looks like this:

{
  "id": "evt_8f3a2b",
  "headline": "...",
  "summary": "...",
  "body": "...",
  "category": "conflict",
  "categories": ["conflict", "diplomacy"],
  "topics": ["Iran", "aircraft", "military"],
  "urgency": "breaking",
  "impact": 9,
  "confidence": 0.96,
  "sourceName": "BBC World Service",
  "sourceId": 14,
  "eventCity": "London",
  "eventCountry": "GB",
  "eventRegion": "Europe",
  "eventLat": 51.51,
  "eventLon": -0.13,
  "language": "en",
  "firstSeenAt": "2026-04-28T22:13:42Z",
  "updatedAt":   "2026-04-28T22:14:08Z",
  "timestamp":   "2026-04-28T22:13:42Z",
  "storyStatus": "developing",
  "corroboration": {
    "count": 4,
    "sources": ["BBC", "NPR", "Al Araby", "France Info"],
    "sourceDetails": [{"name": "BBC", "region": "Europe", "language": "en", "medium": "audio_radio"}]
  },
  "timeline": [
    {"at": "2026-04-28T21:30:00Z", "text": "Initial report on BBC World Service"},
    {"at": "2026-04-28T21:42:00Z", "text": "NPR confirms with named official"}
  ],
  "sources": [
    {"station": "BBC World Service", "quote": "...", "medium": "audio_radio"}
  ]
}

Field semantics worth knowing:

• corroboration.count is independent sources, not raw mentions. Two AP wires republished by different outlets count once.
• eventCity / eventCountry / eventRegion are where the news happened - don't confuse with sources[*].medium (where the broadcaster sits).
• confidence is the LLM extractor's self-reported confidence. Use >= 0.85 for high-confidence reads, >= 0.95 for automated decisioning.
• medium is one of audio_radio, social, structured.

Categories (12)

A story has exactly one primary category plus a multi-category categories[] array:

politics, conflict, economy, disaster, diplomacy, science, health, technology, culture, environment, sports, other.

Errors

Every error response has the same shape:

{"error": "<machine_code>", "message": "<human_message>"}

Every response carries x-request-id. Include it in support tickets.

Rate limits and tiers

• The live wire at https://oruk.ai/ is real-time and free for everyone. Paid tiers are for the programmatic API.
• One API call = one REST request, or one SSE connection open (events on an open SSE stream don't re-bill), or one MCP tool invocation that reaches the backend.
• 429 honors Retry-After. Monthly quotas reset on the 1st of each month.

SSE stream

Trader, Developer, and Enterprise tiers can connect to GET /v1/stream for Server-Sent Events.

Event types:

Reconnect with the Last-Event-ID header to resume from where you left off.

Webhooks (Developer+)

POST /v1/webhooks with:

{
  "url": "https://your-app.com/hooks/oruk",
  "events": ["story", "corroboration"],
  "filters": {
    "categories": ["conflict", "disaster"],
    "min_impact": 7,
    "min_confidence": 0.85,
    "country": "US",
    "topic_match": "earthquake"
  }
}

Every payload is HMAC-SHA256 signed with your webhook secret in the X-Oruk-Signature header. See examples/php/webhook_verify.php, examples/python/webhook_verify.py, and examples/javascript/webhook_verify.js for verification snippets.

Up to 5 active webhooks per account.

Examples by language

Each subfolder has runnable code with a tiny README. Set ORUK_API_KEY in your environment first (export ORUK_API_KEY=ork_xxxxxxxx).

Every example covers four things consistently:

1. Basic - fetch the public feed and a filtered authed list
2. Single story - GET /v1/stories/{id} with parsed corroboration
3. SSE - connect to /v1/stream and handle story / corroboration / heartbeat events
4. Webhook verify - HMAC-SHA256 verification of an inbound webhook (PHP, Python, JS only - same pattern in every language)

MCP server

Already using an LLM agent or IDE? The oruk-mcp package gives Claude Desktop, Cursor, Continue.dev, etc. native access to the oruk API as a Model Context Protocol server.

npx -y oruk-mcp

Configure in Claude Desktop / Cursor:

{
  "mcpServers": {
    "oruk": {
      "command": "npx",
      "args": ["-y", "oruk-mcp"],
      "env": { "ORUK_API_KEY": "ork_xxxxxxxxxxxx" }
    }
  }
}

Without a key, the MCP runs in public mode and serves the freshest 50 stories from /v1/stories/feed. With a key, the full /v1/stories surface is available.

Agent discovery

Building an autonomous agent? oruk publishes machine-readable discovery files:

• https://oruk.ai/.well-known/ai.json - full capability manifest
• https://oruk.ai/.well-known/agent.json - lightweight skill card
• https://oruk.ai/AGENTS.md - operating guide with citation rules
• https://oruk.ai/llms.txt - curated LLM index
• https://oruk.ai/llms-full.txt - exhaustive LLM context

Support

• Email - support@oruk.ai
• Editorial corrections - editorial@oruk.ai
• Sales / Enterprise - sales@oruk.ai or enterprise@oruk.ai
• Status: https://api.oruk.ai/health

License

MIT - see LICENSE. Use these snippets however you like.