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 them, create them and delete them.

Listing needs the decks:read scope. Creating 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" }
  ]
}

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" }
}

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.

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.