Deck fields
This object represents a deck field in Recall. Deck fields are like columns of a database table. The content of a card is structured in deck fields. A deck can have between 2 and 30 deck fields.
Endpoints
POST /v1/deck_fields # Create a new deck fieldPOST /v1/deck_fields/batch # Create multiple deck fieldsPOST /v1/deck_fields/:id # Update a deck fieldGET /v1/deck_fields # List all deck fieldsGET /v1/deck_fields/:id # Get a deck fieldDELETE /v1/deck_fields/:id # Delete a deck field
The deck field object
{"id": "field_5gvuzRdHW2ac","object": "deck_field","autofill_generate_from_deck_fields": [],"autofill_language_from": null,"autofill_language_to": null,"autofill_prompt": null,"autofill_type": null,"deck": "deck_5gvuzRdHW2ac","is_autofill_enabled": false,"key": "french_word","name": "French word","type": "plain_text",}
id stringUnique identifier for the deck field.
object string, value is "deck_field"The type of the object.
The IDs of the deck fields the AI Autofill generates the field value from. When autofill_generate_from_deck_fields is included in expand, each element is a deck field object instead.
autofill_language_from nullable enumIf the autofill_type is translation, this indicates the language to translate the text from.
afarhyazbebsbgcazhhrcsdanlenetfifrgldeelhehihuisiditjaknkkkolvltmkmsmrminenofaplptrorusrskslesswsvtltathtrukurvicyautofill_language_to nullable enumIf the autofill_type is translation or text_to_speech, autofill_language_to indicates the language it translates the text to or generates the audio in.
afarhyazbebsbgcazhhrcsdanlenetfifrgldeelhehihuisiditjaknkkkolvltmkmsmrminenofaplptrorusrskslesswsvtltathtrukurvicyar-AEca-ESyue-CNcmn-CNcs-CZda-DKnl-BEnl-NLen-AUen-GBen-INen-IEen-NZen-SGen-ZAen-USfi-FIfr-FRfr-BEfr-CAhi-INde-DEde-ATde-CHit-ITja-JPko-KRnb-NOpl-PLpt-BRpt-PTes-ESes-MXes-USsv-SEtr-TRautofill_prompt stringThe prompt gives instructions to generate the field value when autofill_type is custom_instruction or image_generation.
Variables are formatted as {{deck_field_id}}. For example, a prompt can be Write a sentence in French using the word {{field_o2AXyzOSksQs}}.
autofill_type nullable enumThe type of AI Autofill to apply to the field.
translationTranslate the field value to the selected language.
answerGenerate a short answer to a question contained in another field.
custom_instructionGenerate any text from one or several other fields, following your own prompt set in autofill_prompt.
text_to_speechGenerate an audio from another field value.
image_generationGenerate an image from another field value.
The ID of the deck the field belongs to. When deck is included in expand, this is a deck object instead.
is_autofill_enabled booleanWhether the AI Autofill is enabled for the field.
key stringReadable identifier automatically derived from name, used to reference the field when creating or updating cards with the API. Each field has a unique key within a deck.
The key tracks the field's name and changes whenever it is renamed. Use id instead if you need a stable reference that never changes.
name stringThe name of the deck field.
type enumThe type of the deck field.
rich_contentText field that allows break lines, <strong>, <em>, and <a> HTML tags.
plain_textText without any formatting. Formatting can be applied uniformly to the field in the card layouts.
audioAudio that can be played in the card (manually or automatically).
imageImage that can be displayed and zoomed on click in the card.
urlURL to a web page. Only valid URLs are accepted.
Create a deck field
A deck field only requires a type to be created.
If you set is_autofill_enabled to true, you also need to set autofill_type, and other attributes depending on the generation type.
A deck can have up to 30 deck fields.
curl https://api.recall.cards/v1/deck_fields \-u YOUR_API_KEY: \-H "Content-Type: application/json" \-d '{"deck": "deck_5gvuzRdHW2ac","name": "Translation","type": "plain_text","autofill_type": "translation","autofill_language_from": "fr","autofill_language_to": "en","autofill_generate_from_deck_fields": ["field_5gvuzRdHW2ac"],"is_autofill_enabled": true}'
deck string requiredThe ID of the deck the field belongs to.
autofill_generate_from_deck_fields array of stringsThe IDs of the deck fields the AI Autofill will generate the field value from. It is optional if you set autofill_prompt when autofill_type is custom_instruction or image_generation. In this case, the IDs will be extracted from the prompt.
autofill_language_from nullable enum, default is nullIf the autofill_type is translation, this indicates the language to translate the text from. It is optional but providing it can result in more accurate translations.
afarhyazbebsbgcazhhrcsdanlenetfifrgldeelhehihuisiditjaknkkkolvltmkmsmrminenofaplptrorusrskslesswsvtltathtrukurvicyautofill_language_to nullable enum, default is nullIf the autofill_type is translation or text_to_speech, autofill_language_to is required and indicates the language to translate the text to or generate the audio in.
afarhyazbebsbgcazhhrcsdanlenetfifrgldeelhehihuisiditjaknkkkolvltmkmsmrminenofaplptrorusrskslesswsvtltathtrukurvicyar-AEca-ESyue-CNcmn-CNcs-CZda-DKnl-BEnl-NLen-AUen-GBen-INen-IEen-NZen-SGen-ZAen-USfi-FIfr-FRfr-BEfr-CAhi-INde-DEde-ATde-CHit-ITja-JPko-KRnb-NOpl-PLpt-BRpt-PTes-ESes-MXes-USsv-SEtr-TRautofill_prompt stringRequired if the autofill_type is custom_instruction or image_generation.
The prompt gives instructions to generate the field value.
It must contain at least one variable to be uniquely generated in each card.
Variables are formatted as {{deck_field_id}}. For example, a prompt can be Write a sentence in French using the word {{field_o2AXyzOSksQs}}.
autofill_type nullable enum, default is nullThe type of AI Autofill to apply to the field. Required if is_autofill_enabled is true.
translationTranslate the field value to the selected language. Can be set on fields of type plain_text or rich_content. Requires autofill_language_to to be set.
answerGenerate a short answer to a question contained in another field. Can be set on fields of type plain_text or rich_content.
custom_instructionGenerate any text from one or several other fields, following your own prompt set in autofill_prompt. Can be set on fields of type plain_text or rich_content.
text_to_speechGenerate an audio from another field value that is of type plain_text or rich_content, and whose ID is included in autofill_generate_from_deck_fields. Can be set on fields of type audio. Requires autofill_language_to to be set.
image_generationGenerate an image from another field value. Can be set on fields of type plain_text or rich_content. Requires autofill_prompt to be set.
is_autofill_enabled boolean, default is falseWhether the AI Autofill is enabled for the field.
If false, any AI Autofill settings will be ignored and settings will be set to default values.
If true, autofill_type and other properties related to the type are required.
name stringThe name of the deck field. Must be between 1 and 35 characters. A default name will be generated if not provided.
type enum requiredThe type of the deck field.
rich_contentText field that allows break lines, <strong>, <em>, and <a> HTML tags.
plain_textText without any formatting. Formatting can be applied uniformly to the field in the card layouts.
audioAudio that can be played in the card (manually or automatically).
imageImage that can be displayed and zoomed on click in the card.
urlURL to a web page. Only valid URLs are accepted.
Returns
Returns the created deck field object.
Batch create deck fields
Create several deck fields in a deck in a single request. Fields created in the same batch can reference each other for AI Autofill, the same way they do when creating a deck with its structure.
Provide the deck once and the fields in the data array. The deck can have up to 30 fields in total, counting the existing fields and the ones created in the batch.
The batch is atomic: if any field is invalid, the entire batch is rejected and no field is created.
curl https://api.recall.cards/v1/deck_fields/batch \-u YOUR_API_KEY: \-H "Content-Type: application/json" \-d '{"deck": "deck_5gvuzRdHW2ac","data": [{"temporary_id": "reading","name": "Reading","type": "plain_text"},{"name": "Pronunciation","type": "audio","is_autofill_enabled": true,"autofill_type": "text_to_speech","autofill_language_to": "ja-JP","autofill_generate_from_deck_fields": ["reading"]}]}'
deck string requiredThe ID of the deck all the fields in the batch belong to.
data array of objects requiredThe deck fields to create. Each object accepts the same parameters as the create endpoint, plus a temporary_id.
temporary_id string, optionalA request-local identifier used to reference this field from another field in the same batch, before any field has a real ID. Use it as a value in another field's autofill_generate_from_deck_fields, or as a variable in another field's autofill_prompt (formatted as {{temporary_id}}).
It only exists for the duration of the request: it is never stored and never returned. Each temporary_id must be unique within the request.
autofill_generate_from_deck_fields array of stringsThe fields the AI Autofill generates the value from. Reference an existing deck field by its ID, or a field created in the same batch by its temporary_id.
Returns
{"object": "list","data": [// Created deck field objects, in the order they appear in the request],}
object string, value is "list"The type of object returned.
data arrayAn array containing the created deck field objects, in the same order as the request.
Update a deck field
curl https://api.recall.cards/v1/deck_fields/field_5gvuzRdHW2ac \-u YOUR_API_KEY: \-H "Content-Type: application/json" \-d '{"is_autofill_enabled": false}'
autofill_generate_from_deck_fields array of stringsThe IDs of the deck fields the AI Autofill will generate the field value from. It is optional if you set autofill_prompt when autofill_type is custom_instruction or image_generation. In this case, the IDs will be extracted from the prompt.
autofill_language_from nullable enum, default is nullIf the autofill_type is translation, this indicates the language to translate the text from. It is optional but providing it can result in more accurate translations.
afarhyazbebsbgcazhhrcsdanlenetfifrgldeelhehihuisiditjaknkkkolvltmkmsmrminenofaplptrorusrskslesswsvtltathtrukurvicyautofill_language_to nullable enum, default is nullIf the autofill_type is translation or text_to_speech, autofill_language_to is required and indicates the language to translate the text to or generate the audio in.
afarhyazbebsbgcazhhrcsdanlenetfifrgldeelhehihuisiditjaknkkkolvltmkmsmrminenofaplptrorusrskslesswsvtltathtrukurvicyar-AEca-ESyue-CNcmn-CNcs-CZda-DKnl-BEnl-NLen-AUen-GBen-INen-IEen-NZen-SGen-ZAen-USfi-FIfr-FRfr-BEfr-CAhi-INde-DEde-ATde-CHit-ITja-JPko-KRnb-NOpl-PLpt-BRpt-PTes-ESes-MXes-USsv-SEtr-TRautofill_prompt stringRequired if the autofill_type is custom_instruction or image_generation.
The prompt gives instructions to generate the field value.
It must contain at least one variable to be uniquely generated in each card.
Variables are formatted as {{deck_field_id}}. For example, a prompt can be Write a sentence in French using the word {{field_o2AXyzOSksQs}}.
autofill_type nullable enum, default is nullThe type of AI Autofill to apply to the field. Required if is_autofill_enabled is true.
translationTranslate the field value to the selected language. Can be set on fields of type plain_text or rich_content. Requires autofill_language_to to be set.
answerGenerate a short answer to a question contained in another field. Can be set on fields of type plain_text or rich_content.
custom_instructionGenerate any text from one or several other fields, following your own prompt set in autofill_prompt. Can be set on fields of type plain_text or rich_content.
text_to_speechGenerate an audio from another field value that is of type plain_text or rich_content, and whose ID is included in autofill_generate_from_deck_fields. Can be set on fields of type audio. Requires autofill_language_to to be set.
image_generationGenerate an image from another field value. Can be set on fields of type plain_text or rich_content. Requires autofill_prompt to be set.
is_autofill_enabled boolean, default is falseWhether the AI Autofill is enabled for the field.
If false, any AI Autofill settings will be ignored and settings will be set to default values.
If true, autofill_type and other properties related to the type are required.
name stringThe name of the deck field. Must be between 1 and 35 characters. Changing the name also updates the field's key accordingly.
Returns
Returns the updated deck field object.
List all deck fields
curl https://api.recall.cards/v1/deck_fields \-u YOUR_API_KEY: \-d '{"deck": "deck_5gvuzRdHW2ac"}'
deck stringFilter the deck fields by the ID of the deck the field belongs to.
limit optional, default is 10The maximum number of deck fields to return, ranging between 1 and 100.
starting_after optionalA cursor to use in pagination. starting_after is a deck field ID that defines your place in the list. For example, if you make a deck field list request and receive 100 deck fields, ending with field_2sdInOpM83eo, your subsequent call can include starting_after=field_2sdInOpM83eo to fetch the next page of the list.
ending_before optionalA cursor to use in pagination. Similarly to starting_after, ending_before is a deck field ID that allows you to fetch deck fields in the previous page of the list.
Returns
{"object": "list","has_more": true,"data": [// Deck field objects...],}
object string, value is "list"The type of object returned.
data arrayAn array containing the deck field objects.
has_more booleanWhether or not there are more elements available after this set. If false, this set comprises the end of the list.
Get a deck field
curl https://api.recall.cards/v1/deck_fields/field_5gvuzRdHW2ac \-u YOUR_API_KEY:
There are no parameters for this endpoint.
Returns
Returns the deck field object.
Delete a deck field
A deck field can be deleted as long as the deck keeps more than 2 deck fields.
Deleting a deck field will also delete the associated content in the cards, and all the card layout fields that reference it. If you delete the last field on the front of a card layout, the affected cards stop appearing in reviews until you add front content back.
curl https://api.recall.cards/v1/deck_fields/field_5gvuzRdHW2ac \-u YOUR_API_KEY: \-X DELETE
There are no parameters for this endpoint.
Returns
{"id": "field_5gvuzRdHW2ac","object": "deck_field","deleted": true}