Recall

Create one or more cards in a deck. Content is keyed by the deck field `key` values, so call get_deck first for the keys and each field's autofill settings. Write the text yourself whenever you can — including text-based AI Autofill fields such as translations, definitions, or example sentences — following each field's autofill_type, autofill_prompt, and autofill_language_to, plus anything decided with the user. Previewing several cards before this call is recommended, not required: a compact table (deck field names as columns, one row per card) lets the user review what they are getting. Past roughly 20 cards, do not list them all — a wall of text that long goes unread. Show an overview instead: how many cards and what they cover, plus 5 to 10 representative rows so the user can see the content format. They review the full set in the Recall app afterwards. Leave image and audio fields empty: Recall owns their generation. Keep trigger_autofill true (the default) so Recall fills any field you leave empty, notably the images and audio. If the deck has an image field with autofill, every card you add spends one of the user's paid image credits — make sure they know and have agreed before adding cards to such a deck. Duplicate cards (same front) are skipped and reported in `skipped`. AI Autofill is all-or-nothing per request: if the remaining quota or image credits can't cover every field it would generate, none are and each card's `autofill.skip_reason` is set — relay the quota notice to the user without suggesting an upgrade or purchase. Content format: rich_content fields take HTML, not Markdown — write "<p><strong>Leningrad</strong> fell in 1941</p>", never "**Leningrad** fell in 1941", whose asterisks can end up displayed as they are. Only these tags survive: <p>, <strong>, <em>, <a href="…">, <br>. So <strong> instead of **, <em> instead of *, <br> or a second <p> for line breaks, and no headings, lists (<ul>/<li> are dropped), code or tables — write values that need none of them. plain_text, number and url fields take bare text with no tags at all. Follow flashcard best practices. Atomic cards: exactly one fact or idea per card — split anything containing "and", a list, or several clauses into separate cards (an enumeration is best learned as one card per element, never as one card listing all of them). Unambiguous front: the front field must admit exactly one correct answer, with a short cue (part of speech, domain, category) when the prompt alone could match several things — especially when cards in the deck could be confused with each other. Minimal answer: the main answer field is the shortest string that proves recall; put nuance, mnemonics, and detail in the deck's supplementary fields (notes, examples) rather than inflating the answer. Prefer concrete examples over abstract phrasing.

add_cards

Add one or more fields (columns) to an existing deck. Existing cards get the new fields empty; fill them afterwards with generate_deck_field_values (if the field has AI Autofill) or by updating cards. Autofill sources reference an existing field by its ID (field_...) or a sibling in this request by its temporary_id. As in create_deck, audio and image fields must have autofill configured (text_to_speech / image_generation) or they stay permanently empty.

add_deck_fields

Duplicate a deck: its fields (with their autofill configuration), layouts, cards, and study order settings. Audio and image assets are copied over rather than regenerated, so the copy costs no autofill quota and no image credits. Learning progress is not carried over — the copy starts fresh, with its first batch of cards already scheduled. Use it whenever the user wants a new deck derived from an existing one, not just for backups: to snapshot a deck before large edits (renaming fields, rewriting cards, bulk deletions), to restructure a variant without touching the original, or as the starting point for an adapted version — a translation, a simplified edition, a different angle on the same material. For an adaptation, always prefer copying over rebuilding with create_deck: the copy keeps the image assets for free (recreating them would cost one image credit per card), plus the layouts and autofill wiring, and you then rewrite the text with update_cards and adjust the fields. The copy counts toward the user's deck limit. Returns the new deck with its fields — show its `url` to the user.

copy_deck

Create an additional card layout for a deck. Each active layout schedules and reviews its own variant of every card, so a second layout is how the user practices a different direction or piece of the same cards: the classic case is a reverse layout (meaning on the front, word on the back) to train production as well as recognition, but a layout can also test one specific field (the reading of a word, a date). Because every active layout multiplies the reviews, propose extra layouts deliberately and confirm with the user rather than creating them on your own initiative. A layout needs 1 to 5 fields on the front and 1 to 12 on the back, and a deck can have up to 6 layouts. Keep the front minimal — only what prompts the recall — and leave out fields that would give the answer away. When the layout tests a non-obvious task, set a short prompt so the learner knows what is asked. Styling guidelines: highlight the main information of each side (the prompt on the front, the core answer on the back) with font_weight bold and the primary color; if its values are generally short use font_size lg, or xl for very short ones like single words or characters (e.g. Japanese words). Secondary information keeps regular weight with md or sm size, and the secondary color for supporting content like hints, readings, or usage notes. An audio field that reads another field aloud goes next to that field with next_to_card_layout_field, on the same side, so its play button sits inline with the text. Set is_primary true only if this layout should become the deck's reference layout (requires every card to have a value on its front); a primary layout is always active. Returns the created layout with its fields.

create_card_layout

Create a new deck from scratch. If it derives from a deck the user already has (a translation, a simplified edition, a restructured variant), do not rebuild it here: use copy_deck and edit the copy — it keeps the image and audio assets for free, plus the layouts and autofill configuration. FIRST decide the shape of the deck, before writing any field. A deck works like a small spreadsheet — each deck field is a column, each card a row — and that structure pays off only when every card really shares the same attributes. Picking the wrong shape is the most common mistake: - Structured (many fields): the subject is a set of comparable items described by the same attributes, and the learner should know several of them per item — vocabulary (word, reading, meaning, example sentence), kanji (character, meaning, on'yomi, kun'yomi, example word), chemical elements, countries and capitals, anatomy, drug dosages. Here be thorough: one field per attribute rather than cramming everything into two. - Unstructured (just "Front" and "Back"): the subject is general knowledge — facts, concepts, events, questions and answers, exam revision, book or lecture notes, trivia. Each card is its own question and they share no common attribute grid. Omit deck_fields entirely to get the two default rich content fields, put the question on the front and the answer on the back, and use the back's rich formatting (a bold key term, a second line of context) when a bare answer is not enough. Do not force a schema onto an unstructured subject. Columns like Date / Location / Who was involved / Why it mattered for a history deck leave most cards half empty or restating the answer, and every review tests five things at once instead of one — the opposite of a good flashcard. An open-ended request ("a deck about WW2 history, about 50 cards") is unstructured by default: choose Front/Back and spend the effort on 50 sharp questions. Go structured only when the attribute grid is obvious from the subject itself; if it is a close call, say in one line what fields you would use and let the user confirm first. In a structured deck, the front (the first field) holds only the prompt the learner is tested on, and the rest goes on the back. Fields can have AI Autofill, where Recall generates a field's value from other fields. An audio or image field MUST have autofill configured or it stays permanently empty: audio needs autofill_type text_to_speech, image needs image_generation. Audio is covered by the monthly quota, but images spend paid image credits (one per card) — be proactive with audio, never with images: add an image field only when the user explicitly asked for images or agreed after you mentioned the credits cost. For any language-learning deck always include an audio field that reads the word in the language being learned (and a second one for the example sentence when present): give the source text field a temporary_id, then set the audio field's is_autofill_enabled true, autofill_type text_to_speech, autofill_generate_from_deck_fields to that temporary_id, and autofill_language_to to the language's voice locale. E.g. a Japanese field with temporary_id "jp" plus { "type": "audio", "is_autofill_enabled": true, "autofill_type": "text_to_speech", "autofill_language_to": "ja-JP", "autofill_generate_from_deck_fields": ["jp"] }. add_cards fills audio and images by default (trigger_autofill is true), so you never write them yourself. Also configure autofill on the text fields the user may add cards to later in the app. When you add the cards yourself with add_cards, write the text values directly rather than relying on autofill: it is immediate, reviewable, and saves the user's autofill quota (a text field you fill is automatically skipped by autofill). Leave audio and image fields empty so Recall generates them. Omitting deck_fields gives the deck two rich content fields, "Front" and "Back". Returns the created deck with its fields, whose `key` values are used with add_cards. The deck starts with one card layout showing the first field on the front and the rest on the back; use edit_card_layout_fields or create_card_layout to restyle it or add a layout testing another direction (e.g. a reverse layout).

create_deck

Permanently delete a card layout. This also deletes its card variants, so the scheduling state and learning progress of the cards under this layout are lost for good — when the user may want the layout back later, deactivate it with update_card_layout instead, which just removes it from reviews. The primary layout can't be deleted. Make sure the user explicitly asked for the deletion.

delete_card_layout

Permanently delete one or more cards, including their content and review history. This cannot be undone, so make sure the user explicitly asked for it. Cards are deleted one by one; the result reports each outcome.

delete_cards

Permanently delete a deck field and its content on every card of the deck. This cannot be undone, so make sure the user explicitly asked for it. Fails if the deck would drop below its minimum number of fields.

delete_deck_field

Change which deck fields a card layout displays, and how: `add` places deck fields in the layout, `update` restyles, reorders or moves fields already in it, `remove` takes fields out. A deck field is not displayed anywhere until it is placed in a layout, so after add_deck_fields, read the deck's layouts with get_deck and decide with the user where each new field belongs: on the back as supporting information (the common case), on the front if it is part of the prompt, or left out of a layout that tests something else. Removing a field only stops displaying it — the deck field and the cards' content are untouched, and it can be added back later. Pass every change in one call rather than one call per field. The groups are applied in order (add, then update, then remove) and each is validated as a whole, so `update` can do what a field-by-field edit cannot, like swapping two fields between the front and the back. They are not a single transaction: if a later group fails, the earlier ones stay applied and the error says what was written. Each side must keep at least one field, with at most 5 on the front and 12 on the back. Returns the layout's fields after the edit. Styling guidelines: highlight the main information of each side (the prompt on the front, the core answer on the back) with font_weight bold and the primary color; if its values are generally short use font_size lg, or xl for very short ones like single words or characters (e.g. Japanese words). Secondary information keeps regular weight with md or sm size, and the secondary color for supporting content like hints, readings, or usage notes. An audio field that reads another field aloud goes next to that field with next_to_card_layout_field, on the same side, so its play button sits inline with the text.

edit_card_layout_fields

Fill a field's value on every card of the deck with AI Autofill, using the field's autofill configuration (the field must have is_autofill_enabled true). Generation runs in the background and can take a few minutes on large decks. Values the user edited manually are preserved by default; set overwrite_manually_updated true only if the user explicitly wants those regenerated too. The whole run must fit in the remaining monthly AI Autofill quota (or image generation credits for image fields), otherwise the call fails — relay the quota message to the user without suggesting an upgrade or purchase. For an image field the run consumes one paid image credit per card, so confirm with the user before generating images.

generate_deck_field_values