Mochi API: Create a Card, Read It Back, and Update It
You send a card to Mochi, then lose the response. Should your script send it again? That decision gets easier when each source note has a saved card ID. Start your Mochi API integration with one question, read it back, then improve its answer using the same ID.

This AI-assisted guide follows Mochi's official documentation, checked November 18, 2026. The examples and acceptance worksheet are original and haven't been run against an authenticated Mochi account. Nibomo publishes this guide and builds a separate flashcard app.
Set up a small rehearsal
Create an empty practice deck called API rehearsal, without a template. This makes the result easy to inspect: one source note should produce one card. For cards that use fields, see the Mochi templates guide.
Mochi's pricing page lists API keys as a Pro feature. Manage keys in Account Settings. Authentication uses HTTP Basic Auth, with the key as username and an empty password. API authentication
The commands below use Bash, curl, and a text editor. If your terminal uses Zsh, enter bash first; this also works from an existing Bash session:
bash
In that Bash session, enter the key at a hidden prompt:
read -r -s -p 'Mochi API key: ' MOCHI_API_KEY
printf '\n'
Paste the key and press Enter. Keep this terminal open for the remaining commands. Work in a fresh directory so the response files won't overwrite another rehearsal.
Save this worksheet in a local text file before sending anything. The source key is your own label, not a Mochi API field.
| Item | What to record |
|---|---|
| Source key | python-list-length-001 |
| Deck ID | Copy after checking the destination |
| Card ID | Leave empty until creation is confirmed |
| Creation status | Start with not sent |
| Accepted content | Keep the create and update JSON files |
Find the deck before writing
Fetch the decks:
curl --silent --show-error --fail-with-body \
--user "${MOCHI_API_KEY:?Enter the API key first}:" \
--header 'Accept: application/json' \
--output decks.json \
--write-out 'HTTP %{http_code}\n' \
https://app.mochi.cards/api/decks
cat decks.json
Find API rehearsal in docs and copy its id into the worksheet. Lists can use bookmark pagination; a missing deck may be on another page. Pagination reference
Continue only after a successful request and an exact deck match. These commands print the HTTP status and save the response body. If curl reports an error, stop and inspect that file before moving to another step. Reading a saved file with cat doesn't mean the request succeeded.
Create one card and keep its receipt
Save this as create-card.json, replacing REPLACE_WITH_DECK_ID with the ID from your worksheet:
{
"deck-id": "REPLACE_WITH_DECK_ID",
"content": "Which Python built-in returns the number of items in a list?\n---\n`len`.\n\nCapture reference: `python-list-length-001`."
}
Card creation takes content and deck-id and returns the created card. Create-card reference
The \n escapes put --- on its own line between the question and answer, as in the Markdown import walkthrough. The capture reference is there to help you find this practice card later. It doesn't enforce uniqueness.
Change the worksheet's creation status to outcome unknown, then send this request once:
curl --silent --show-error --fail-with-body \
--user "${MOCHI_API_KEY:?Enter the API key first}:" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-binary @create-card.json \
--output create-response.json \
--write-out 'HTTP %{http_code}\n' \
https://app.mochi.cards/api/cards/
cat create-response.json
After a successful request with a 2xx response, copy the returned id into your worksheet and change the status to confirmed. Keep create-response.json. If the response is incomplete or has no usable ID, leave the status unresolved and inspect the practice deck before doing anything else. Rerunning creation to get a cleaner response could leave you with another card.
Read the card, then improve its answer
Set the variable to the returned ID, replacing the whole placeholder:
MOCHI_CARD_ID='REPLACE_WITH_RETURNED_CARD_ID'
Retrieve that card:
curl --silent --show-error --fail-with-body \
--user "${MOCHI_API_KEY:?Enter the API key first}:" \
--header 'Accept: application/json' \
--output read-response.json \
--write-out 'HTTP %{http_code}\n' \
"https://app.mochi.cards/api/cards/${MOCHI_CARD_ID:?Set the confirmed card ID first}"
cat read-response.json
Compare id, deck-id, and content with your worksheet and payload. Open the card in Mochi too: the question should appear first, followed by the answer and capture reference.
Save update-card.json with a more useful answer:
{
"content": "Which Python built-in returns the number of items in a list?\n---\n`len`. For example, `len([4, 8, 12])` returns `3`.\n\nCapture reference: `python-list-length-001`."
}
Mochi uses POST to the card's ID URL for updates. Update-card reference
curl --silent --show-error --fail-with-body \
--user "${MOCHI_API_KEY:?Enter the API key first}:" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-binary @update-card.json \
--output update-response.json \
--write-out 'HTTP %{http_code}\n' \
"https://app.mochi.cards/api/cards/${MOCHI_CARD_ID:?Set the confirmed card ID first}"
cat update-response.json
The :? expression stops the request if the ID is unset or empty. That's especially useful on the update: an empty ID would otherwise point at the collection URL used for creation.
Repeat the read command and inspect the card again. Use this acceptance worksheet before automating more notes:
| Check | Passing result |
|---|---|
| Identity | The read-back id matches the saved ID |
| Destination | deck-id matches API rehearsal |
| Stored answer | content includes len([4, 8, 12]) and result 3 |
| Rendered sides | One question side, then the updated answer side |
| Deck contents | Exactly one card with this capture reference |
These are expected results for your rehearsal, not reported test results. Once finished, clear the key with unset MOCHI_API_KEY and enter exit to leave the Bash session you opened.
Keep uncertain writes out of the rerun queue
Mochi allows one concurrent API request per account and documents 429 responses. Its reference makes no idempotency promise for creation. Rate limits
A timeout leaves a practical question: did the card arrive before the connection broke? Keep the worksheet unresolved. Inspect the saved response and look in API rehearsal for the capture reference. If the card exists, record its ID and read it back. If you can't establish the outcome, investigate before another create request.
For an interrupted update, you already have the ID. Read that card and compare its answer with update-card.json before deciding whether another write is needed. A fresh read is also how you check a correction after a successful update.
When this becomes a script, save the source-key-to-card-ID mapping before processing that source again. A known card ID directs the next correction to that card. An unresolved creation attempt should stay unresolved until you've checked it; sending it through the normal create path loses the distinction your worksheet preserved.
For occasional file transfers, Markdown import may be enough. For the broader app decision, see the Mochi review.