# mentioned.fm — Predictions API

Concrete claims made on podcasts, mapped to live Kalshi markets.
Same data the /predictions tab renders. No auth required.

## Endpoint

GET /api/predictions
  Returns paginated JSON: { data: Prediction[], pagination, filters }.

## Query parameters

  limit        integer, 1..200, default 50
  offset       integer, >= 0, default 0
  match_type   one of: direct | proxy | none      (optional)
  confidence   one of: high | medium | speculative (optional)
  horizon      one of: near | medium | long | unspecified (optional)

## Response shape

  {
    "data": [
      {
        "id": "uuid",
        "podcast_id": "uuid",
        "segment_id": "uuid | null",
        "speaker": "string",                 // speaker name (diarized)
        "text": "string",                    // model-extracted claim
        "quote": "string",                   // verbatim quote from transcript
        "start_time_seconds": 1234,          // jump-to second in episode
        "topic": "string | null",
        "confidence": "high | medium | speculative | null",
        "horizon":    "near | medium | long | unspecified | null",
        "match_type": "direct | proxy | none",
        "matched_market": {                  // null when match_type=none
          "ticker": "string",
          "event_ticker": "string",
          "title": "string",
          "subtitle": "string | null",
          "close_time": "ISO8601",
          "rules": "string | null",
          "side": "YES | NO | CHECK",        // recommended bet side
          "why": "string",                   // model's rationale
          "kalshi_url": "https://kalshi.com/...",
          "yes_bid": 42,                     // cents, 0..100
          "yes_ask": 45,
          "last_price": 44,
          "volume": 12345,
          "volume24h": 678,
          "open_interest": 9000,
          "snapshot_ts": "ISO8601"
        },
        "source": "string",
        "run_id": "string | null",
        "created_at": "ISO8601",
        "updated_at": "ISO8601",
        "podcast": {
          "id": "uuid",
          "video_id": "string | null",       // YouTube id, when known
          "title": "string",
          "thumbnail_url": "string | null",
          "channel_name": "string | null",
          "audio_url": "string | null"
        },
        "segment": {                         // null when not aligned
          "id": "uuid",
          "segment_index": 0,
          "title": "string | null",
          "start_time": 1200,                // seconds
          "end_time": 1500
        }
      }
    ],
    "pagination": {
      "limit": 50,
      "offset": 0,
      "total": 1234,
      "next_offset": 50                      // null when at the end
    },
    "filters": {
      "match_type": null,
      "confidence": null,
      "horizon": null
    }
  }

## Ordering

Results are sorted by match_type (direct, then proxy, then none) and then
by created_at descending. This means the most actionable, recent picks
surface first.

## Pagination pattern

Page through by passing the previous response's pagination.next_offset
back as ?offset=. When next_offset is null, you have read every row that
matches your filters.

  curl 'https://mentioned.fm/api/predictions?limit=50&offset=0'
  curl 'https://mentioned.fm/api/predictions?limit=50&offset=50'
  curl 'https://mentioned.fm/api/predictions?match_type=direct&horizon=long'

## Notes for agents

- Prices in matched_market are cents (0..100). YES bid+NO bid ≈ 100.
- start_time_seconds is the precise moment the claim was uttered;
  use it to construct episode timestamps (e.g. youtu.be/<video_id>?t=NNN).
- The set is small and refreshed weekly. Cache aggressively, refetch daily.