REST Reference

Six endpoints under /v1/*. Every endpoint accepts the same auth modes (Bearer key or x402 micropayment), gates on the same per-key tier table, and returns either a strict MindResponse shape or the error envelope.

Base URL: https://api.cloven.cloud

All endpoints are GET (the cite endpoint accepts both GET and POST). All responses are application/json except /v1/subscribe, which is text/event-stream.

GET /v1/fresh

Latest compacted Mind State + brief + citations + freshness.

Query params.

Response (200).

{
  "state": { "...": "pack-specific schema" },
  "brief": "Bitcoin holding above 95k [1]. ETH funding rates flipped negative...",
  "citations": [
    {
      "ref": 1,
      "sourceId": "coingecko",
      "url": "https://www.coingecko.com",
      "fetchedAt": "2026-05-24T11:58:46Z"
    }
  ],
  "freshness": {
    "generatedAt": "2026-05-24T11:58:46Z",
    "ageSeconds": 134
  }
}

Errors. 401 invalid_token, 402 payment_required, 403 pack_access_denied, 404 pack_not_found, 429 quota_exhausted, 503 state_unavailable (first-pulse race).

GET /v1/brief

Brief-only. Identical contract to /v1/fresh minus the state field. Cheaper when the caller already has a state cache.

Query params. pack (required).

Response (200).

{
  "brief": "Bitcoin holding above 95k [1]...",
  "citations": [ ... ],
  "freshness": { "generatedAt": "...", "ageSeconds": 134 }
}

GET /v1/search

Top-k case-insensitive walk over the cached state JSON tree. Word-boundary matches score 1.0; substring matches score 0.5. Returns paths into the state with their values.

Query params.

Response (200).

{
  "matches": [
    { "path": "top_movers[3].symbol", "value": "ETH", "score": 1 },
    { "path": "narratives[1].evidence[0]", "value": "ETH funding flipped...", "score": 0.5 }
  ],
  "total": 12,
  "freshness": { "generatedAt": "...", "ageSeconds": 134 }
}

GET /v1/snapshot

Time-travel: historical Mind State at the requested timestamp.

Query params.

Response (200). Same shape as /v1/fresh, with freshness.generatedAt pinned to the historical pulse. brief is empty for snapshots: use /v1/brief for current prose. Pro+ tiers can read 30 days back; Team+ tiers 365 days.

Errors. 404 snapshot_not_found (the requested minute is outside the hot window or before the pack existed), 400 invalid_at.

GET /v1/subscribe

SSE pulse stream. Headers cannot be set on the browser EventSource API, so the API key is passed as the token query param. x402 is not supported on SSE. There is no per-call payment model for a long-lived stream.

Query params.

Response. text/event-stream with three event types:

event: pulse
data: { "pack": "crypto", "state": {...}, "ts": "2026-05-24T11:58:46Z" }
 
event: delta
data: { "pack": "crypto", "state": {...}, "ts": "2026-05-24T12:03:46Z" }
 
: keepalive 1716552134000

pulse fires every 15s with the latest cached state. delta fires when the cached generatedAt advances (a fresh compaction landed). : keepalive is a comment frame that stops proxies from closing idle connections. The stream stays open until the client disconnects or the auth key is revoked.

Details: SSE subscribe.

GET /v1/cite

Resolve a [N] citation anchor (1-indexed) to its underlying source. The anchor index matches the order of pack.sources, stable across the lifetime of the pack version.

Query params.

Response (200).

{
  "citation": {
    "ref": 1,
    "sourceId": "coingecko",
    "url": "https://www.coingecko.com",
    "fetchedAt": "2026-05-24T11:58:46Z"
  },
  "source": {
    "id": "coingecko",
    "name": "CoinGecko",
    "publicUrl": "https://www.coingecko.com"
  },
  "freshness": { "generatedAt": "...", "ageSeconds": 134 }
}

Errors. 404 citation_not_found (ref out of range), 400 invalid_ref.

Common headers

TypeScript types

The same MindResponse and Citation interfaces used inside the codebase ship as part of @cloven/sdk, see the SDK reference for import paths. Pack-specific state shapes live under @cloven/sdk/packs/<id>.