# Use ChatGPT or Claude to Build Your Cramdeck Decks > **Version 1.0.0** · Updated 2026-04-26 · See [CHANGELOG](./CHANGELOG.md) > **Audience:** you, a Cramdeck user who wants to use an AI assistant > (ChatGPT, Claude, Gemini, etc.) to generate flashcard decks and add > them to your account — without copy-pasting card-by-card. > > *Polska wersja: [`end-user-setup.pl.md`](./end-user-setup.pl.md).* This guide walks you through wiring up an AI assistant so you can say *"make me a 30-card deck on the French Revolution"* and have it land in your Cramdeck library a few seconds later. **Privacy:** CramDeck is operated by JMS Sieracki sp. z o.o. Read the [Privacy Policy](/privacy) and [Terms](/terms). Do not put patient-identifying health data, payment card numbers, government IDs, or other people’s personal data into prompts or decks. Revoke PATs or unlink OAuth under **Profile → Integrations**. There are two integration patterns. Pick whichever matches your tools: | Pattern | What the AI does | Setup effort | Best for | |---|---|---|---| | **Author-only** | Returns a `.deck.md` file you import yourself | 2 minutes | Free ChatGPT, Claude.ai chat, any LLM you can paste a prompt into | | **Tool-use** | Calls the Cramdeck API directly and adds decks for you | 10 minutes | Custom GPTs (Plus), Claude Projects with tools, MCP, custom integrations | Both patterns produce identical content; the difference is where the upload happens. --- ## Step 1 — Create a Personal Access Token (PAT) You only need this for the **tool-use** pattern. For author-only you can skip ahead to Step 2. 1. Open Cramdeck and go to **Profile → Integrations**. 2. Click **Create token**. 3. Name it something memorable (`ChatGPT custom GPT`, `Claude project`). 4. Choose scopes: - `decks:read` — let the AI list and read your decks (recommended). - `decks:write` — let the AI create and edit decks (required to add decks for you). 5. Click **Generate**. 6. **Copy the token now.** It starts with `cdk_pat_…` and is shown exactly once. We never store the plaintext — if you lose it you'll need to issue a new one. Treat the token like a password. Anyone with it can read/write your decks within the scopes you granted. --- ## Step 2 — Author-only pattern (any LLM) Use this if you don't want to wire up an action / tool. The AI generates the `.deck.md` content, you save it as a file, and you import it via Cramdeck's UI. ### One-time setup 1. Open the LLM of your choice (ChatGPT free, Claude.ai, Gemini, etc.). 2. Start a new chat / project / custom instructions area. 3. Open the Cramdeck **author system prompt**: 4. Copy its full contents and paste it into: - **ChatGPT** — the *Custom Instructions* "How would you like ChatGPT to respond?" field, **or** the system message of a Custom GPT, **or** just the first message of the chat. - **Claude.ai** — Project knowledge, *or* the *System prompt* field if you're using the workbench, *or* the first message of the chat. - **Anything else** — find the field labeled "system prompt", "instructions", or "persona" and paste it there. ### Daily use Now in any chat with that assistant, ask things like: - *"Make me a 20-card deck on the Krebs cycle, biology, English."* - *"A French A1 vocab deck — 25 words I'd hear ordering coffee."* - *"Convert this list of TypeScript interview questions into a deck."* The assistant will reply with **exactly one fenced markdown code block** containing a complete `.deck.md` document. To import it: 1. Click the copy button on the code block. 2. Save the contents to a file. The convention is `.deck.md`, e.g. `krebs-cycle.deck.md`. 3. In Cramdeck, click **My decks → ⋮ → Import deck** and upload the file. 4. The deck appears in your library, ready to study. That's it. No tokens, no API setup. --- ## Step 3 — Tool-use pattern (ChatGPT custom GPT) Use this if you have ChatGPT Plus and want a "talk to it, deck appears" experience. ### Create the custom GPT 1. In ChatGPT, click **Explore GPTs → Create**. 2. Skip the conversational builder. Click the **Configure** tab. 3. **Name**: "Cramdeck Builder" (or whatever you like). 4. **Description**: "Adds AI-generated flashcard decks to my Cramdeck account." 5. **Instructions**: paste the full contents of . 6. **Capabilities**: turn off everything you don't need (Web Browsing, Code Interpreter, DALL·E) unless you specifically want them. ### Add the action 1. Scroll to **Actions → Create new action**. 2. **Authentication**: - Type: **API Key** - API Key: paste your `cdk_pat_…` token. - Auth Type: **Bearer**. 3. **Schema**: paste the full contents of . 4. **Privacy policy URL**: a link to your own privacy notice (required by ChatGPT before you can publish, but a placeholder is fine while the GPT is private to you). 5. Click **Save**. ### Test it In a new chat with your custom GPT: > List my decks. The first time, ChatGPT will ask permission to call the Cramdeck API — approve it. You should see your decks listed. Then: > Make me a 15-card deck on the French Revolution. Tag it "history" and > "high-school". Visibility: private. Within a few seconds, refresh Cramdeck and the deck should be there. --- ## Step 4 — Tool-use pattern (Claude Projects) If you use Claude.ai with Projects: 1. Create a new Project. 2. **Custom instructions**: paste the contents of `ai-agent-tool-use-prompt.md` (same file as above). 3. **Project knowledge**: upload (or link to) the five sample decks at and the OpenAPI spec at `/api/v1/integrations/openapi.json`. This gives Claude concrete examples of valid `.deck.md` files. 4. For tool execution, use Claude's native API with the Tool Use feature plus a tiny adapter that maps Claude's tool calls to HTTP requests against `https://your-cramdeck-host/api/v1/integrations/...` with your PAT in the `Authorization` header. The Cramdeck team is working on a first-party MCP server that will eliminate this step — track the roadmap at `/docs/integrations`. If you're not comfortable writing the adapter, use the **author-only** pattern (Step 2) inside Claude — it works perfectly with Claude Projects and requires no code at all. --- ## Step 5 — Test it end-to-end Try these prompts to verify all four content types render correctly in Cramdeck: | Test | Prompt | What to verify | |---|---|---| | Plain text | *"5-card deck of basic Spanish greetings."* | Text shows as plain text on both sides. | | Markdown | *"5-card deck on Python list comprehensions, with code examples."* | Code blocks have syntax highlighting. | | HTML | *"5-card deck of common chemistry compounds (H2O, CO2, etc.). Use HTML for the formulas."* | Subscripts render properly (H2O). | | LaTeX | *"5-card deck of basic calculus identities. Use LaTeX for the equations."* | Equations render as math, not raw `\frac{...}`. | | Images | *"5-card deck of European country flags. Use flagcdn.com for the images."* | Flag images appear; alt text is set. | If any of these don't render the way you'd expect, check Cramdeck's **Profile → Integrations → Audit log** to see exactly what was sent. --- ## Troubleshooting | Symptom | Likely cause | Fix | |---|---|---| | `401 UNAUTHORIZED` | Token missing, malformed, or copied with extra whitespace. | Re-issue the PAT and re-paste it cleanly. | | `401 TOKEN_REVOKED` | You revoked the token (or it expired) but the AI still has it. | Issue a new PAT and update the GPT/project settings. | | `403 FORBIDDEN` | Token is missing the `decks:write` scope. | Re-issue the PAT and check both `decks:read` and `decks:write`. | | `400 PARSE_FAILED` | The AI emitted a malformed `.deck.md` (usually missing `lang:` in the frontmatter). | Tell it: "lang is required in the frontmatter; use BCP-47 codes like en, fr, pl." | | `400 SCHEMA_INVALID` mentioning `imageUrl` | The AI used an `http://` or base64 image URL. | Tell it: "image URLs must be https — replace with an https URL or remove the image." | | `400 TOO_MANY_CARDS` | The AI built a deck with more than 250 cards. | Ask it to split into multiple decks of ≤ 250. | | `429 RATE_LIMITED` | You've hit the per-minute quota. | Wait 60 seconds, then retry. | | Deck imports but renders weirdly | Wrong `frontType` / `backType` in `extras`. | Tell it the right content type explicitly: "use frontType: latex" / "use frontType: html". | If a problem keeps recurring, the **author** and **tool-use** prompts both contain a "Common rejections" / "Error envelope" section the AI will read on its next turn — sometimes pointing it back to its own instructions is enough to fix it. --- ## Privacy and security - Your PAT is **only** stored where you put it — in your custom GPT, in your Claude project, or in your local script. Cramdeck stores only a bcrypt hash, never the plaintext. - Every API call is recorded in your **audit log** (Profile → Integrations → token name → Activity). You can see exactly which decks the AI created or modified. - You can **revoke** any token instantly from Profile → Integrations. Revoked tokens stop working within seconds; the AI will start receiving `401 TOKEN_REVOKED` and won't be able to read or modify anything. - Scope your tokens narrowly. If an AI only needs to add new decks, give it `decks:write` and not `decks:read`. If you only want to read decks (e.g. for analytics), give it `decks:read` only. --- ## What's next The current API focuses on **whole-deck** operations (create, list, read, update metadata). Coming soon: - Per-card CRUD (`POST /decks/{id}/cards`, `PATCH /cards/{id}`). - A first-party MCP server, so any MCP-compatible client (Claude Desktop, Cursor, Continue) can use Cramdeck without a custom adapter. - Webhooks for "deck imported" events. - Scoped collaboration (let an AI edit only one specific deck). Track progress and submit feedback on `/docs/integrations`.