API

Two on-ramps. One credit wallet.

Drive Study Decks from your own code over REST, or connect an AI assistant — including the Ounie AI Team — over MCP for a native tool surface. Both run the same generation pipeline and draw your shared Ounie credits (1 credit = 1¢), never overdrawing. Cards are grounded in your private Ounie brains, so generation authenticates as you — there is no keyless / x402 rail (there's nothing to sell without a brain behind it).

Authentication · two keys, one wallet

Every REST route and MCP tool accepts a bearer token in the Authorization header, or as ?api_key=for clients that can't set headers.

sdk_live_…— this app's key

Mint it on Dashboard → API keys (up to 5, shown once). Lists, reads, exports, and reviews decks. It can't generate — a per-app key has no way to reach your private brains.

ounie_live_… — your Ounie master key

Your ounie.com developer key, with app access enabled. It authenticates as you upstream, so it unlocks generation — and works across every Ounie app, drawing the same wallet. Manage it at ounie.com → Settings → API keys.

A cookie session (the dashboard) works on the REST routes too — it's the same route.

MCP · for AI assistants and the Ounie AI Team

Streamable HTTP at /api/mcp (legacy SSE at /api/sse).

Endpoint  https://study.ounie.com/api/mcp
Header    Authorization: Bearer sdk_live_…   (or ounie_live_… to generate)

# Ounie AI Team (TabTab) — its HTTP MCP entry can't set headers, so
# the key rides the URL:
https://study.ounie.com/api/mcp?api_key=ounie_live_…

Tool	What it does	Cost
generate_deck	Generate a cited flashcard deck from your brain(s). Master key only.	1 credit / card
list_decks	List your decks with due-card counts.	free
get_deck	One deck with all cards + cited sources.	free
export_deck	Export a deck as json \| md \| tsv (Anki/Quizlet).	free
review_card	Grade a card (again \| hard \| good \| easy); SM-2-lite.	free
get_credit_balance	Spendable Ounie credits + monthly included.	free
get_pricing	Per-action pricing. No auth required.	public
whoami	The key's owner + whether it can generate.	free

// Tool call → generate_deck  (needs the ounie_live_ master key)
{ "brain_ids": ["…"],       // 1–5 of your brains
  "topic": "spaced repetition",
  "card_count": 20 }
→ { "deck_id": "…", "cards_generated": 20,
    "credits_spent": 20, "thin_context": false }

REST · the same endpoints the dashboard uses

Send Authorization: Bearer sdk_live_… (or ?api_key=) on any of these.

POST/api/decks— Generate a deck

{ "brain_ids": ["…"], "topic": "…", "card_count": 20, "title": "…" }

Bills 1 credit per card actually produced. Needs a cookie session OR the Ounie master key (ounie_live_) — a per-app sdk_live_ key is refused with a 403 use-your-master-key message. Returns { deck_id, cards_generated, credits_spent, thin_context }.

GET/api/decks— List your decks

Free. Returns { decks } with due-card counts.

GET/api/decks/{id}— Deck detail + due cards

Free. Returns { deck, cards, due }.

GET/api/decks/{id}/export— Export a deck

Free. ?format=json (default) | md | tsv.

POST/api/decks/{id}/review— Grade a card

{ "card_id": "…", "grade": "good" }

Free. grade = again | hard | good | easy.

DELETE/api/decks/{id}— Delete a deck

Free. Cards + reviews cascade.

GET/api/brains— Your Ounie brains

For picking brain_ids. Needs a cookie or the master key (upstream access).

Shape of an exported deck

GET /api/decks/{id}/export (or the export_deck MCP tool).

{
  "id": "…", "title": "…", "topic": "…",
  "brain_names": ["…"], "cards_count": 20, "thin_context": false,
  "cards": [
    {
      "front": "A precise question or cloze prompt",
      "back": "The concise, complete answer.",
      "source": {              // every card cites its brain page
        "brain_id": "…", "slug": "…", "title": "…",
        "url": "https://ounie.com/dashboard/brains/…/documents/…"
      }
    }
  ]
}