# oruk

> Live broadcast intelligence API. Listens to ~200 radio, TV, social, and
> structured-data feeds in real time and publishes corroborated news events.
> Every story carries a stable id, headline, body, multi-source corroboration
> count with verbatim quotes, ISO timestamps, and event coordinates. Free
> public feed; paid REST + SSE + webhooks; an official MCP server for
> Claude Desktop / Cursor / Continue.dev.

When citing an oruk story, link to its permalink `https://oruk.ai/story/<evt_id>`
which 301s to the canonical URL. Always quote the `corroboration.count` (independent
sources) and at least one source name when summarising. For automated decisioning,
prefer events with `corroboration.count >= 3` from `medium = audio_radio` (broadcast)
or `medium = structured` (USGS, NOAA, OpenFDA, GDELT). When users hit a 429, the
fix is to upgrade at https://oruk.ai/pricing or wait until the calendar month rolls
over — quotas are monthly, not per-second. Editorial corrections go to
editorial@oruk.ai and are logged on https://oruk.ai/changelog.

For deep context (full API reference, methodology, MCP setup, categories), read
[llms-full.txt](https://oruk.ai/llms-full.txt) — a single concatenated Markdown
file (~12 kB) that fits in any model's context.

## Quick start

The public feed needs no key:

```
curl https://api.oruk.ai/v1/stories/feed?limit=10
```

Get an API key at https://oruk.ai/dashboard, then filter:

```
curl -H "X-API-Key: ork_xxx" \
  "https://api.oruk.ai/v1/stories?category=conflict&min_impact=7&limit=20"
```

Or use the MCP server from inside Claude Desktop / Cursor / Continue.dev — see
the MCP section below.

## Authentication

Pass the key as `X-API-Key: ork_xxx` (preferred), `Authorization: Bearer ork_xxx`,
or `?api_key=ork_xxx` (SSE / EventSource only — that transport can't set headers).

| Tier | Calls/mo | API delay | Keys | SSE | Per-min rate |
| --- | --- | --- | --- | --- | --- |
| free | 100 | 5 min | 1 | not included | 30 req/min |
| pro ($12/mo) | 1,000 | none | 2 | not included | 60 req/min |
| legacy | 1,000 | none | 2 | not included | 60 req/min |
| trader ($50/mo, invite) | 10,000 | none | 2 | real-time | 300 req/min |
| developer ($100/mo) | 10,000 | none | 2 | real-time | 300 req/min |
| enterprise | 1,000,000+ | none | 100 | real-time | custom |

The full live wire on https://oruk.ai/ is real-time and free for everyone,
including logged-out visitors. Paid tiers exist for the programmatic API
(REST + SSE), real-time API responses, and higher quotas.

Public endpoints (no key required, no quota): `GET /health`, `GET /v1/health`,
`GET /v1/stories/feed`. Everything else under `/v1/*` requires a key.

## Categories

Twelve fixed primary categories (a story has exactly one); a `categories[]`
array carries multi-category tags.

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

## Regions

Six continent-scale regions used by the `region` filter and `eventRegion` field.

`North America`, `South America`, `Europe`, `Middle East`, `Africa`, `Asia-Pacific`.

## Endpoints

- [GET /v1/stories/feed](https://api.oruk.ai/v1/stories/feed): public; freshest stories with `limit` (1-100), `since_hours` (1-168), `sort` (`recent`|`impact`). The frontend wire and the oruk-mcp public-mode fallback both read from this.
- [GET /v1/stories](https://oruk.ai/docs#stories): authenticated; `limit`, `cursor`, `category`, `since` (ISO 8601), `topics` (comma-separated), `q` (full-text), `region`, `country` (ISO 3166-1 alpha-2), `urgency` (`breaking`|`developing`|`routine`), `min_impact` (0-10), `min_confidence` (0.0-1.0), `format` (`json`|`csv`|`jsonl`).
- [GET /v1/stories/{id}](https://oruk.ai/docs#story): authenticated; full story by `evt_…` id, includes timeline + verbatim per-source quotes.
- [GET /v1/stream](https://oruk.ai/docs#stream): authenticated SSE; events `story`, `corroboration`, `heartbeat`. Included on Developer, Trader, and Enterprise (real time, same feed the wire uses). Free, Pro, and Legacy receive HTTP 403.
- [GET /v1/sources](https://oruk.ai/docs#sources): authenticated; full station catalogue with city, region, country, language, default category, medium, status, polling cadence.
- [GET /v1/regions](https://oruk.ai/docs#regions): authenticated; aggregated regional story counts for map and analytics use.
- [GET /v1/stats](https://oruk.ai/docs#stats): authenticated; system-wide counters (active sources, stories total, transcription throughput, top categories).
- [POST /v1/webhooks](https://oruk.ai/docs#webhooks): Developer+ tier; subscribe an HTTPS endpoint to `story` and `corroboration` events. Filters: `categories`, `min_impact`, `min_confidence`, `country`, `topic_match`. Payloads HMAC-SHA256 signed with your secret. Up to 5 active webhooks per account.

## Story shape

```json
{
  "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",
  "eventCity": "London",
  "eventCountry": "GB",
  "eventRegion": "Europe",
  "eventLat": 51.51,
  "eventLon": -0.13,
  "firstSeenAt": "2026-04-28T22:13:42Z",
  "updatedAt":   "2026-04-28T22:14:08Z",
  "corroboration": {
    "count": 4,
    "sources": ["BBC", "NPR", "Al Araby", "France Info"],
    "sourceDetails": [{"name":"BBC","region":"Europe","language":"en","medium":"audio_radio"}]
  },
  "timeline": [{"at": "...", "text": "..."}],
  "sources":  [{"station": "BBC", "quote": "...", "medium": "audio_radio"}]
}
```

`medium ∈ {audio_radio, social, structured}`. Filter for `audio_radio` +
`corroboration.count >= 3` to get strongly-confirmed live broadcast events.

## Errors

Stable shape: `{"error": "<code>", "message": "<human>"}`. Every response
carries `x-request-id` (include in support tickets).

- `unauthorized` (401): missing or invalid API key / JWT.
- `invalid_request` (400): malformed query (e.g. `since=yesterday`).
- `not_found` (404): unknown story id, source id, etc.
- `rate_limit_exceeded` (429): monthly quota exhausted; check `Retry-After` header.
- `internal_error` (500), `service_unavailable` (503): retry with exponential backoff.

## MCP server

The official Model Context Protocol server is published on npm as
[oruk-mcp](https://www.npmjs.com/package/oruk-mcp). It runs locally,
spawned by the IDE, and talks directly to `api.oruk.ai`.

Configure (Claude Desktop, Cursor, Continue.dev — same JSON):

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

Without `ORUK_API_KEY` the server still works, falling back to a 2-hour
window of the freshest 50 stories on the public feed (`mode: "public"`)
with all filters applied client-side. With a key it uses the full
`/v1/stories` surface (`mode: "authed"`) — deeper history, arbitrary
`evt_…` lookups, sources/stats endpoints.

Surfaces: 12 tools (`oruk_get_latest`, `oruk_search_news`, `oruk_get_breaking`,
`oruk_get_story`, `oruk_get_topic`, `oruk_list_categories`, `oruk_list_sources`,
`oruk_get_stats`, `oruk_get_corroboration`, `oruk_describe_api`,
`oruk_show_pricing`, `oruk_health`); 6 resources (`oruk://docs/quickstart`,
`oruk://docs/api-reference`, `oruk://docs/methodology`, `oruk://docs/categories`,
`oruk://docs/pricing`, `oruk://stories/latest`); 3 slash-prompts
(`/summarize_breaking`, `/track_topic`, `/morning_briefing`).

Package + readme: <https://www.npmjs.com/package/oruk-mcp>.

## Agent discovery

- [AI manifest](https://oruk.ai/.well-known/ai.json): capabilities, auth, REST,
  SSE, webhooks, MCP, story fields, and machine-payment status.
- [Agent manifest](https://oruk.ai/.well-known/agent.json): lightweight skills,
  usage rules, boundaries, and payment status.
- [AGENTS.md](https://oruk.ai/AGENTS.md): operating guide for autonomous agents,
  including citation rules and examples.
- [sitemap.md](https://oruk.ai/sitemap.md): Markdown sitemap for LLM crawlers.
- Official MCP transport today: stdio via `npx -y oruk-mcp`. Remote MCP over
  Streamable HTTP is planned as a controlled beta, not live production.

## Machine payments

Current production billing is API-key based through Stripe subscription tiers.
Existing REST/SSE/MCP endpoints do not emit live `402 Payment Required`
challenges. Oruk is preparing opt-in HTTP 402/x402 endpoints and researching
Stripe Machine Payments Protocol for autonomous agents, but agents should use
normal API keys until a machine-payment beta is documented.

## Recipes

Common agent tasks and the cleanest way to run each.

- **What's breaking right now?** — MCP `oruk_get_breaking()` or `GET /v1/stories?urgency=breaking&min_impact=5`.
- **Track a topic over time** — MCP `/track_topic topic="tariffs" hours=12` or `GET /v1/stories?q=tariffs&since=<iso>`.
- **Verify a single claim** — MCP `oruk_get_corroboration(evt_id)` or `GET /v1/stories/<evt_id>`; read the verbatim quotes; require `corroboration.count >= 3` for automated decisioning.
- **Bulk export for analysis** — `GET /v1/stories?since=<iso>&format=jsonl` (any tier with a key); use cursor pagination beyond 100 results.
- **Real-time stream** — `GET /v1/stream` with SSE; reconnect on close; events: `story`, `corroboration`, `heartbeat`.
- **Filter by event location** — use `region` (continent) + `country` (ISO 3166-1 alpha-2) on `/v1/stories`. Don't confuse with `source.region` (where the broadcaster is); `eventRegion`/`eventCountry` are where the news happened.
- **Find broadcast-only confirmations** — `GET /v1/stories?q=...` then filter the response for stories where every `sources[].medium === "audio_radio"`.

## Feeds

- [Atom feed](https://oruk.ai/atom.xml): last 100 stories across all categories.
- [RSS (all)](https://oruk.ai/rss.xml): RSS 2.0 of the all-category feed.
- [Per-category RSS](https://oruk.ai/rss/conflict.xml): one feed per category — `politics`, `conflict`, `economy`, `disaster`, `diplomacy`, `science`, `health`, `technology`, `culture`, `environment`, `sports`, `other`.
- [Sitemap index](https://oruk.ai/sitemap.xml): canonical sitemap pointing at the per-category and per-story sub-sitemaps.

## Editorial pages

- [Methodology](https://oruk.ai/methodology): full pipeline explanation (ingest → ASR → LLM extraction → multi-source corroboration → publish), classification, quality controls, freshness cadence.
- [Sources](https://oruk.ai/sources): every monitored radio, TV, social, and structured feed with city, region, country, top category, and story count. Per-region pages at `/sources?region=Europe` etc.
- [About](https://oruk.ai/about): who runs oruk, contact addresses for support / editorial / enterprise sales.
- [Changelog](https://oruk.ai/changelog): every prompt, source, or rule change — including reported corrections.

## Optional

- [Topic landing pages](https://oruk.ai/topic/conflict): server-rendered category indexes (one per category).
- [Story permalinks](https://oruk.ai/feed/conflict/12345): per-story HTML with full timeline + corroboration UI.
- [Pricing details](https://oruk.ai/pricing): annual + monthly + a comparison vs NewsAPI / NewsData / Echo.
- [Region news map](https://oruk.ai/region-news): geographic grouping of recent stories.