Plain-text version for scripts and AI assistants: /llms.txt
# Flashcards API
Base URL: https://flashcards.alexramalho.dev
A spaced-repetition flashcard service (Anki's SM-2 scheduler). Cards added here show up in the
Flashcards iPhone app for the same account.
## Auth
Create a key in the app: Settings → API keys → New key. Send it on every request:
Authorization: Bearer fc_xxxxxxxx
## Add cards
`POST /cards` — one card, or many with `cards`. The deck is created if it doesn't exist.
curl -X POST https://flashcards.alexramalho.dev/cards \
-H "Authorization: Bearer $FLASHCARDS_KEY" -H "Content-Type: application/json" \
-d '{
"deck": "Chinese",
"cards": [
{ "front": "你好", "back": "hello", "extra": "nǐ hǎo", "speak": "你好", "lang": "zh-CN",
"tags": ["hsk1"], "reverse": true }
]
}'
Card fields:
| field | | |
|---|---|---|
| front | required | Question side. |
| back | required | Answer side. |
| extra | optional | Shown under the answer: pinyin, example sentence, notes. Newlines are kept. |
| speak | optional | Text read aloud (text-to-speech). Spoken when the side containing it is shown, otherwise on reveal. |
| lang | optional | Voice for `speak`, a BCP-47 code: `zh-CN`, `zh-TW`, `ja-JP`, `en-US`... |
| tags | optional | Array of strings. |
| reverse | optional | `true` also creates the back→front card. The pair is never shown on the same day. |
| deck / deckId | optional | Per-card deck override. Default is the request's `deck`, else "Default". |
Up to 1000 cards per request. By default a card whose `front` already exists in the same deck is
skipped (returned in `skipped`); send `"skipDuplicates": false` to allow duplicates.
Response: `{ "created": [Card], "skipped": [{ index, front, reason, existingId }] }`
## Other endpoints
| | |
|---|---|
| GET /decks?tz=Europe/Berlin | Decks with total cards and today's due counts `{ new, learning, review }`. |
| POST /decks | `{ name, description?, newPerDay? }` (default 20 new cards a day). |
| PATCH /decks/:id | `{ name?, description?, newPerDay? }` |
| DELETE /decks/:id | Deletes the deck and its cards. |
| GET /cards?deckId=&q=&state=&limit=&offset= | Search/browse. `state`: new, learning, review, relearning. |
| GET /cards/:id | One card. |
| PATCH /cards/:id | Any card field, plus `suspended` (bool) and `reset: true` (forget progress). |
| DELETE /cards/:id | Delete one card. |
| POST /cards/delete | `{ ids: [...] }` bulk delete. |
| GET /study?deckId=&tz= | Today's queue, with answer-button interval previews. |
| POST /cards/:id/review | `{ rating: 1-4 }` again / hard / good / easy. |
| POST /reviews/undo | Undo the latest review. |
| GET /stats?tz= | Streak, reviews today, totals, 30-day retention. |
| GET /keys, POST /keys, DELETE /keys/:id | Manage API keys. |
| GET /me, DELETE /me | Account; DELETE removes the account and all data. |
Errors are `{ "error": "message" }` with a 4xx/5xx status.
## Tips for making good cards (Chinese)
- One fact per card. Front: 汉字 (or a short phrase). Back: the meaning. Extra: pinyin with tone marks
and a short example sentence with its translation.
- Set `speak` to the Chinese text and `lang` to `zh-CN` so the app pronounces it.
- Use `reverse: true` for vocabulary you also want to produce, not just recognise.
- Tag by source or level (`hsk1`, `lesson-3`) so cards are easy to find later.