Edit and delete cards with the API

Both editing and deleting need a key with the cards:write scope, and both come in a single-card form and a batch form.

Edit one card

curl -X PATCH https://yalango.com/api/v1/decks/8sKd92mfPqR1xLvBn4Tz/cards/Lp4nVx8QmRt2YsKd \
  -H "Authorization: Bearer yal_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "target": "el gato" }'

{
  "card": {
    "card_doc_id": "Lp4nVx8QmRt2YsKd",
    "source": "the cat",
    "target": "el gato",
    "custom_fields": { "kL9mQ2xVnB4t": "masculine" },
    "created_timestamp": "2026-03-02T18:05:12.000Z",
    "last_updated_timestamp": "2026-03-14T11:41:02.000Z"
  }
}

Only the fields you send are changed. Leaving source out of the request above leaves it exactly as it was - it does not clear it.

Three fields can be changed: source, target and custom_fields. That is the whole list. Pinyin and audio are generated for you and are rejected if you try to set them, and a card's languages, privacy and author belong to the deck rather than the card.

Edit up to 100 cards

Send the same fields, with card_doc_id on each entry:

curl -X PATCH https://yalango.com/api/v1/decks/8sKd92mfPqR1xLvBn4Tz/cards \
  -H "Authorization: Bearer yal_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cards": [
      { "card_doc_id": "Lp4nVx8QmRt2YsKd", "target": "el gato" },
      { "card_doc_id": "Bq7WcZ3jHf5TnXvA", "source": "the house", "target": "la casa" }
    ]
  }'

{
  "updated": 2,
  "cards": [ { "card_doc_id": "Lp4nVx8QmRt2YsKd", "...": "..." } ]
}

The batch is all or nothing. If one entry names a card that does not exist, or one that lives in a different deck, nothing is written and the error says which entry was at fault.

Custom fields are merged, not replaced

Sending custom_fields changes only the ids you include:

curl -X PATCH https://yalango.com/api/v1/decks/8sKd92mfPqR1xLvBn4Tz/cards/Lp4nVx8QmRt2YsKd \
  -H "Authorization: Bearer yal_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "custom_fields": { "kL9mQ2xVnB4t": "feminine" } }'

Any other custom field on that card keeps its value. To clear one, send it as an empty string. To find the ids, see Custom fields with the API.

Delete one card

curl -X DELETE https://yalango.com/api/v1/decks/8sKd92mfPqR1xLvBn4Tz/cards/Lp4nVx8QmRt2YsKd \
  -H "Authorization: Bearer yal_your_key_here"

{ "deleted": true, "card_doc_id": "Lp4nVx8QmRt2YsKd" }

Delete up to 100 cards

The list of ids travels in the body, so this one is a POST to /cards/delete rather than a DELETE. A request body on DELETE is allowed by the HTTP spec but quietly dropped by enough clients and proxies to be worth avoiding.

curl -X POST https://yalango.com/api/v1/decks/8sKd92mfPqR1xLvBn4Tz/cards/delete \
  -H "Authorization: Bearer yal_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "card_ids": ["Lp4nVx8QmRt2YsKd", "Bq7WcZ3jHf5TnXvA"] }'

{ "deleted": 2, "card_ids": ["Lp4nVx8QmRt2YsKd", "Bq7WcZ3jHf5TnXvA"] }

Like editing, it is all or nothing: if any id is unknown or belongs to another deck, nothing is deleted.

This endpoint accepts an Idempotency-Key header, so a request that times out can be retried without any risk of a second attempt hitting cards that were added in between.

Deleting cannot be undone

There is no trash and no recovery. A deleted card is gone, along with its statistics, and the deck's card count and your card quota both go back down.

The word itself may stay in your vocabulary if another deck or table still contains it - vocabulary is shared across everything that uses the same word pair. It disappears from your vocabulary only when the last card for it is gone.

If you only want to stop reviewing a word rather than lose it, pause it in the vocabulary list instead. That keeps the card and its history.

Rules

• 1 to 100 cards per batch request.
• source and target are each up to 2000 characters.
• An edit must leave at least one of source and target non-empty.
• The same card id cannot appear twice in one request.
• Every card must belong to the deck in the URL.

Editing a card's target regenerates its audio

Changing target invalidates the card's pronunciation audio, so on Premium it is regenerated in the background - the same as when you edit a card in the web app. For Mandarin decks, pinyin is regenerated too.

Because of that work, a full 100-card edit is charged more heavily against the rate limit than a read is. Batching is still far cheaper than 100 separate requests.