Custom fields with the API

Custom fields are the extra columns you add to a deck yourself - an example sentence, a gender, a mnemonic. The API can list, create, rename and delete them, and choose which one the Cloze game uses.

Listing needs the decks:read scope. Creating, editing and deleting need decks:write.

List a deck's custom fields

curl https://yalango.com/api/v1/decks/8sKd92mfPqR1xLvBn4Tz/custom-fields \
  -H "Authorization: Bearer yal_your_key_here"

{
  "custom_fields": [
    { "id": "kL9mQ2xVnB4t", "name": "Gender", "type": "text", "cloze_sentence": false }
  ]
}

The id is the important part: it is the key you use in a card's custom_fields object when adding or editing cards. The name is only what the field is called in the web app, and the API never accepts it as a key.

Create a custom field

curl -X POST https://yalango.com/api/v1/decks/8sKd92mfPqR1xLvBn4Tz/custom-fields \
  -H "Authorization: Bearer yal_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Example sentence" }'

{
  "custom_field": { "id": "Rt7vBn2QxKm9", "name": "Example sentence", "type": "text", "cloze_sentence": false }
}

Use the id from the response straight away:

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": { "Rt7vBn2QxKm9": "El perro come." } }'

Types

Type	What it is for
text	A single value. The default if you leave type out.
list	Several comma-separated values in one field.

Rules

• name is required, 1 to 60 characters.
• A deck cannot have two custom fields with the same name. The API returns 409 custom_field_exists and tells you the id of the field that already has that name, so you can use it instead of creating a duplicate.
• A deck can have at most 50 custom fields.

The cloze field

The Cloze game shows a card's example sentence with the target word blanked out. One text field per deck can be marked as the sentence it uses. Send "cloze_sentence": true when creating the field, or set it on an existing one:

curl -X PATCH https://yalango.com/api/v1/decks/8sKd92mfPqR1xLvBn4Tz/custom-fields/Rt7vBn2QxKm9 \
  -H "Authorization: Bearer yal_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "cloze_sentence": true }'

• Marking a field unmarks whichever field had the flag before.
• Only text fields can be the cloze field. A list field returns 400.
• If a sentence uses a different form of the word than the card, wrap that form in asterisks, like Yesterday I *went* home. for the card "to go".
• Without a marked field, the game uses the first text field that contains the card's exact target word.

Rename a custom field

The same PATCH route takes a new name, on its own or together with cloze_sentence. Values stored on cards are kept. The type cannot be changed, because that would change how every stored value is read.

Delete a custom field

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

{ "deleted": true, "id": "kL9mQ2xVnB4t" }

This removes the field from the deck and clears the values it held on every word in your vocabulary. It cannot be undone, and it affects every card in the deck at once.

Deleting a field that does not exist returns 404 custom_field_not_found rather than pretending to have worked.

Pinyin and audio are not custom fields

Pinyin and pronunciation audio are generated by Yalango and live on the card itself rather than in the deck's custom fields. They will not appear in the list above, and they cannot be created or deleted here - nor set through a card write. That is deliberate: a generated reading you overwrote by accident is hard to notice and harder to get back.