Card layout fields

This object represents a field in a card layout in Recall. Card layout fields define how deck fields are displayed in a card layout.

Endpoints

POST     /v1/card_layout_fields                # Create a new card layout field
POST     /v1/card_layout_fields/batch_create   # Create multiple card layout fields
POST     /v1/card_layout_fields/:id            # Update a card layout field
POST     /v1/card_layout_fields/batch_update   # Update multiple card layout fields
GET      /v1/card_layout_fields                # List all card layout fields
GET      /v1/card_layout_fields/:id            # Get a card layout field
DELETE   /v1/card_layout_fields/:id            # Delete a card layout field

The card layout field object

{
  "id": "layout_field_7h8j9k0l1m2n",
  "object": "card_layout_field",
  "card_layout": "layout_yT9ktMcdzg4e",
  "color": "primary",
  "deck_field": "field_5gvuzRdHW2ac",
  "font_size": "md",
  "font_weight": "bold",
  "is_front": true,
  "next_to_card_layout_field": null,
  "order": 1,
}
id string

Unique identifier for the card layout field.

object string, value is "card_layout_field"

The type of the object.

card_layout stringExpandable

The ID of the card layout the field belongs to. When card_layout is included in expand, this is a card layout object instead.

color enum

The color of the text.

primary
Primary (highest contrast)
secondary
Secondary
tertiary
Tertiary
deck_field stringExpandable

The ID of the deck field to display. When deck_field is included in expand, this is a deck field object instead.

font_size enum

The font size of the text.

sm
Small
md
Normal
lg
Large
xl
Huge
font_weight enum

The font weight of the text.

regular
Regular
bold
Bold
is_front boolean

Whether the field is displayed on the front of the card.

next_to_card_layout_field nullable stringExpandable

If the field is of type audio, it may be placed next to another field of type plain_text or rich_content. This is the ID of the card layout field it is linked to. When next_to_card_layout_field is included in expand, this is a card layout field object instead.

order integer

The position of the field within its side of the card (front or back).

Create a card layout field

curl https://api.recall.cards/v1/card_layout_fields \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "card_layout": "layout_yT9ktMcdzg4e",
    "deck_field": "field_5gvuzRdHW2ac",
    "order": 1,
    "is_front": true,
    "color": "primary",
    "font_size": "md",
    "font_weight": "bold"
  }'
card_layout string required

The ID of the card layout the field belongs to.

deck_field string required

The ID of the deck field to display.

color enum, default is primary

The color of the text.

primary
Primary (highest contrast)
secondary
Secondary
tertiary
Tertiary
font_size enum, default is md

The font size of the text.

sm
Small
md
Normal
lg
Large
xl
Huge
font_weight enum, default is regular

The font weight of the text.

regular
Regular
bold
Bold
is_front boolean, default is true

Whether the field is displayed on the front of the card.

next_to_card_layout_field nullable string, default is null

If the field is of type audio, it may be placed next to another field of type plain_text or rich_content. This is the ID of the card layout field it is linked to.

order integer, optional

The position of the field within its side of the card (front or back).

Returns

Returns the created card layout field object.

Batch create card layout fields

To create several card layout fields in a single request, you need to provide the card_layout they will belong to.

In some cases, you may want to place an audio field next to a plain_text or rich_content field. To do this, give the plain_text or rich_content field a temporary_id and pass it as the next_to_card_layout_field value in the audio field. Each temporary ID must be unique within the request. It is never stored or returned.

The batch is atomic: if any card layout field is invalid, the entire batch is rejected and no field is created.

curl https://api.recall.cards/v1/card_layout_fields/batch_create \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "card_layout": "layout_yT9ktMcdzg4e",
    "data": [
      {
        "temporary_id": "reading_line",
        "deck_field": "field_5gvuzRdHW2ac",
        "is_front": true
      },
      {
        "deck_field": "field_uYS9PpONoqTP",
        "is_front": true,
        "next_to_card_layout_field": "reading_line"
      }
    ]
  }'
card_layout string required

The ID of the card layout all the fields in the batch belong to.

data array of objects required

The card layout fields to create. Each object describes a card layout field and accepts the same parameters as the create endpoint, plus a temporary_id.

deck_field string required

The ID of the deck field to display. A deck field can appear at most once per layout.

temporary_id string, optional

A request-local identifier for this layout field, used by another field's next_to_card_layout_field in the same batch. It is never stored or returned, and must be unique within the request.

color enum, default is primary

The color of the text.

primary
Primary (highest contrast)
secondary
Secondary
tertiary
Tertiary
font_size enum, default is md

The font size of the text.

sm
Small
md
Normal
lg
Large
xl
Huge
font_weight enum, default is regular

The font weight of the text.

regular
Regular
bold
Bold
is_front boolean, default is true

Whether the field is displayed on the front of the card.

next_to_card_layout_field nullable string, default is null

Places this field next to another field in the same layout. Reference an existing layout field by its ID, or a field created in the same batch by its temporary_id. Only valid for an audio field placed next to a plain_text or rich_content field on the same side.

order integer, optional

The position of the field within its side of the card (front or back).

Returns

{
  "object": "list",
  "data": [
    // Created card layout field objects, in the order they appear in the request
  ],
}
object string, value is "list"

The type of object returned.

data array

An array containing the created card layout field objects, in the same order as the request.

Update a card layout field

curl https://api.recall.cards/v1/card_layout_fields/layout_field_7h8j9k0l1m2n \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "font_weight": "bold"
  }'
color enum

The color of the text.

primary
Primary (highest contrast)
secondary
Secondary
tertiary
Tertiary
font_size enum

The font size of the text.

sm
Small
md
Normal
lg
Large
xl
Huge
font_weight enum

The font weight of the text.

regular
Regular
bold
Bold
is_front boolean

Whether the field is displayed on the front of the card.

next_to_card_layout_field nullable string, default is null

If the field is of type audio, it may be placed next to another field of type plain_text or rich_content. This is the ID of the card layout field it is linked to.

order integer

The position of the field within its side of the card (front or back).

Returns

Returns the updated card layout field object.

Batch update card layout fields

Update several fields of a card layout in a single request: provide the card_layout once, and the updates in the data array, each carrying the card_layout_field to update. A layout field can appear only once per batch.

The batch is all-or-nothing and validated against the layout's final state, after all the updates are applied. If any update is invalid, the entire batch is rejected and no field is changed, with the error's param pointing at the offending item (for example data[1].next_to_card_layout_field).

Because validation runs on the final state, the batch allows changes that are impossible one field at a time — for example swapping two fields between the front and the back, which would transiently leave a side empty if done in two separate requests.

curl https://api.recall.cards/v1/card_layout_fields/batch_update \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "card_layout": "layout_yT9ktMcdzg4e",
    "data": [
      { "card_layout_field": "layout_field_7h8j9k0l1m2n", "is_front": false },
      { "card_layout_field": "layout_field_2sdInOpM83eo", "is_front": true, "font_weight": "bold" }
    ]
  }'
card_layout string required

The ID of the card layout all the fields in the batch belong to.

data array of objects required

The updates to apply. Each object carries the card_layout_field to update plus the same optional parameters as the update endpoint: only the parameters present are changed.

card_layout_field string required

The ID of the card layout field to update. The field must belong to card_layout.

A field moved to the other side (is_front) without an explicit order is appended after the destination side's fields.

Returns

{
  "object": "list",
  "data": [
    // Updated card layout field objects, in the order they appear in the request
  ]
}

List all card layout fields

curl https://api.recall.cards/v1/card_layout_fields \
  -u YOUR_API_KEY: \
  -d '{
    "card_layout": "layout_yT9ktMcdzg4e"
  }'
card_layout string

Filter the card layout fields by the ID of the card layout they belong to.

limit optional, default is 10

The maximum number of card layout fields to return, ranging between 1 and 100.

starting_after optional

A cursor to use in pagination. starting_after is a card layout field ID that defines your place in the list. For example, if you make a card layout field list request and receive 100 card layout fields, ending with layout_field_2sdInOpM83eo, your subsequent call can include starting_after=layout_field_2sdInOpM83eo to fetch the next page of the list.

ending_before optional

A cursor to use in pagination. Similarly to starting_after, ending_before is a card layout field ID that allows you to fetch card layout fields in the previous page of the list.

Returns

{
  "object": "list",
  "has_more": false,
  "data": [
    // Card layout field objects...
  ],
}
object string, value is "list"

The type of object returned.

data array

An array containing the card layout field objects.

has_more boolean

Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

Get a card layout field

curl https://api.recall.cards/v1/card_layout_fields/layout_field_7h8j9k0l1m2n \
  -u YOUR_API_KEY:

There are no parameters for this endpoint.

Returns

Returns the card layout field object.

Delete a card layout field

curl https://api.recall.cards/v1/card_layout_fields/layout_field_7h8j9k0l1m2n \
  -u YOUR_API_KEY: \
  -X DELETE

There are no parameters for this endpoint.

Returns

{
  "id": "layout_field_7h8j9k0l1m2n",
  "object": "card_layout_field",
  "deleted": true
}