# Oruk Agent Guide

Oruk is a live broadcast intelligence API. Use it to find, verify, stream, and
cite corroborated real-time news events from radio, TV, social, and structured
feeds.

## Best Entry Points

- Public feed: <https://api.oruk.ai/v1/stories/feed>
- REST and SSE docs: <https://oruk.ai/docs>
- Curated LLM index: <https://oruk.ai/llms.txt>
- Full LLM context: <https://oruk.ai/llms-full.txt>
- Capability manifest: <https://oruk.ai/.well-known/ai.json>
- MCP server: `npx -y oruk-mcp`

## Authentication

The public feed needs no key. Full REST filtering, individual story lookups,
SSE, sources, stats, CSV/JSONL export, and webhooks require an Oruk API key.

Use one of:

```http
X-API-Key: ork_xxxxxxxxxxxx
Authorization: Bearer ork_xxxxxxxxxxxx
```

For EventSource/SSE clients that cannot set headers, use `?api_key=ork_xxx`.
Never put API keys in public repos, screenshots, browser JavaScript, or shared
prompts.

## MCP Usage

Use the official local MCP server for coding tools and desktop agents:

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

`ORUK_API_KEY` is optional. Without it, the MCP server uses the public feed and
marks output as `mode: "public"`. With a key, it unlocks authenticated search,
sources, stats, and arbitrary story lookups.

## Citation Rules

- Link to `https://oruk.ai/story/{evt_id}`.
- Include `corroboration.count`.
- Name at least one confirming source when available.
- Prefer stories with `corroboration.count >= 3` for automated briefings.
- Prefer `medium = audio_radio` or `medium = structured` when users need the
  strongest evidence trail.
- Do not state details that are not present in the returned story, timeline,
  sources, or corroboration block.

## Common Tasks

### Get Latest Public Stories

```bash
curl "https://api.oruk.ai/v1/stories/feed?limit=10&sort=recent"
```

### Search Authenticated Stories

```bash
curl -H "X-API-Key: ork_xxxxxxxxxxxx" \
  "https://api.oruk.ai/v1/stories?q=tariff&since=2026-04-29T00:00:00Z&limit=10"
```

### Get One Story

```bash
curl -H "X-API-Key: ork_xxxxxxxxxxxx" \
  "https://api.oruk.ai/v1/stories/evt_8f3a2b"
```

### Stream Updates

```bash
curl -N -H "X-API-Key: ork_xxxxxxxxxxxx" \
  "https://api.oruk.ai/v1/stream"
```

## Boundaries

- Do not scrape dashboards, admin pages, login flows, audit logs, or private API
  routes.
- Treat Oruk as live intelligence, not an official emergency alert system.
- Respect `robots.txt` and API rate limits.
- If a story is locked, delayed, or missing fields, say so instead of guessing.

## Machine Payments

Production billing is currently API-key plus Stripe subscription tiers. Oruk is
preparing for autonomous machine-payment rails, but live HTTP 402/x402 and
Stripe Machine Payments Protocol billing endpoints are not enabled yet. Agents
should use normal API keys until Oruk documents an active machine-payment beta.