Card layouts

This object represents a card layout in Recall. Card layouts define how fields are displayed in a card. There can be at most 6 card layouts per deck.

Endpoints

POST     /v1/card_layouts       # Create a new card layout
POST     /v1/card_layouts/:id   # Update a card layout
GET      /v1/card_layouts       # List all card layouts
GET      /v1/card_layouts/:id   # Get a card layout
DELETE   /v1/card_layouts/:id   # Delete a card layout

The card layout object

{
  "id": "layout_yT9ktMcdzg4e",
  "object": "card_layout",
  "card_layout_fields": ["layout_field_7h8j9k0l1m2n"],
  "created_at": "2025-11-30T12:34:56Z",
  "deck": "deck_5gvuzRdHW2ac",
  "is_active": true,
  "is_primary": true,
}

id string

Unique identifier for the card layout.

object string, value is "card_layout"

The type of the object.

card_layout_fields array of stringsExpandable

An array of the card layout field IDs belonging to the card layout. When card_layout_fields is included in expand, each element is a card layout field object instead.

created_at string

The date and time the card layout was created. RFC 3339–formatted UTC datetime.

deck stringExpandable

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

is_active boolean

Whether the card layout is currently being used to display cards in reviews.

is_primary boolean

Whether the card layout is the primary card layout of the deck. The primary card layout is the default layout used to display your cards. It can't be deleted.

When you set a layout to be primary, it will first verify that all the cards have at least a value in the front side of the card. If not, the request will fail and return an error. If it succeeds, the layout will be set as primary and other layouts will be set as not primary.

Create a card layout

A card layout must be created with its card_layout_fields. Each card_layout_field defines how each deck field looks and where it is placed in that layout. A layout must have between 1 and 5 fields on its front and between 1 and 12 fields on its back. All deck fields don't have to be included in the layout.

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.

curl https://api.recall.cards/v1/card_layouts \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "deck": "deck_5gvuzRdHW2ac",
    "is_active": true,
    "card_layout_fields": [
      {
        "temporary_id": "front_word",
        "deck_field": "field_5gvuzRdHW2ac",
        "is_front": true,
        "order": 1
      },
      {
        "deck_field": "field_pX8sR2bTq1Lm",
        "is_front": true,
        "order": 2,
        "next_to_card_layout_field": "front_word"
      },
      {
        "deck_field": "field_uYS9PpONoqTP",
        "is_front": false,
        "order": 1
      }
    ]
  }'

deck string required

The ID of the deck the card layout belongs to.

is_active boolean, default is true

Whether the card layout should be used to display cards in reviews.

is_primary boolean, default is false

Whether the card layout is the primary card layout of the deck. The primary card layout is the default layout used to display your cards. It can't be deleted.

When you create a primary layout, it will be set as primary and other layouts will be set as not primary.

card_layout_fields array of objects required

The fields to create in the card layout. Each object displays an existing deck field and accepts the same parameters as the create card layout field endpoint, plus a temporary_id. A layout must have between 1 and 5 fields on its front and between 1 and 12 fields on its back.

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 used to reference this layout field from another field's next_to_card_layout_field, before any field has a real ID. It is never stored and never returned, and must be unique within the request.

next_to_card_layout_field string, optional

Places this field next to another field in the same layout, referenced by that field's temporary_id (it is created in the same request, so it has no ID yet). Only valid for an audio field placed next to a plain_text or rich_content field.

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.

order integer, optional

The position of the field within its side of the card. If omitted, it is inferred from the field's position in the array within its side (front or back).

Returns

Returns the created card layout object.

Update a card layout

curl https://api.recall.cards/v1/card_layouts/layout_yT9ktMcdzg4e \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false
  }'

is_active boolean, default is true

Whether the card layout should be used to display cards in reviews.

is_primary boolean, default is false

Whether the card layout is the primary card layout of the deck. The primary card layout is the default layout used to display your cards. It can't be deleted.

When you update a layout to be primary, it will be set as primary and other layouts will be set as not primary.

Returns

Returns the updated card layout object.

List all card layouts

curl https://api.recall.cards/v1/card_layouts \
  -u YOUR_API_KEY: \
  -d '{
    "deck": "deck_5gvuzRdHW2ac"
  }'

deck string

Filter the card layouts by the ID of the deck the card layout belongs to.

limit optional, default is 10

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

starting_after optional

A cursor to use in pagination. starting_after is a card layout ID that defines your place in the list. For example, if you make a card layout list request and receive 100 card layouts, ending with layout_2sdInOpM83eo, your subsequent call can include starting_after=layout_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 ID that allows you to fetch card layouts in the previous page of the list.

Returns

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

object string, value is "list"

The type of object returned.

data array

An array containing the card layout 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

curl https://api.recall.cards/v1/card_layouts/layout_yT9ktMcdzg4e \
  -u YOUR_API_KEY:

There are no parameters for this endpoint.

Returns

Returns the card layout object.

Delete a card layout

Deleting a card layout will also delete all its card layout fields.

curl https://api.recall.cards/v1/card_layouts/layout_yT9ktMcdzg4e \
  -u YOUR_API_KEY: \
  -X DELETE

There are no parameters for this endpoint.

Returns

{
  "id": "layout_yT9ktMcdzg4e",
  "object": "card_layout",
  "deleted": true
}

Cards

Card layout fields