Decks

This object represents a deck in Recall. All cards must belong to a deck and have their content structured in its deck fields. A deck also has one or several card layouts that define the design of cards.

Endpoints

POST     /v1/decks       # Create a new deck
POST     /v1/decks/:id   # Update a deck
GET      /v1/decks       # List all decks
GET      /v1/decks/:id   # Get a deck
DELETE   /v1/decks/:id   # Delete a deck

The deck object

{
  "id": "deck_5gvuzRdHW2ac",
  "object": "deck",
  "card_layouts": ["layout_yT9ktMcdzg4e"],
  "cards_count": 217,
  "created_at": "2025-11-30T12:34:56Z",
  "deck_fields": ["field_5gvuzRdHW2ac", "field_uYS9PpONoqTP"],
  "last_reviewed_at": "2025-11-22T12:42:56Z",
  "name": "My deck",
  "settings": {
    "max_new_reviews_per_day": 10,
    "target_retention": 90,
  },
}

id string

Unique identifier for the deck.

object string, value is "deck"

The type of the object.

card_layouts array of stringsExpandable

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

cards_count integer

The number of cards in the deck.

created_at string

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

deck_fields array of stringsExpandable

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

last_reviewed_at nullable string

The date and time the last card was reviewed in the deck. RFC 3339–formatted UTC datetime. Null if no card has been reviewed in the deck yet.

name string

The name of the deck. Must be between 1 and 60 characters.

settings object

An object containing the settings of the deck.

max_new_reviews_per_day integer, default is 10

The maximum number of new reviews added each day. Fewer are added if many are already due.

target_retention integer, default is 90

The minimum percentage of cards of the deck the user aims to remember at any given time. Must be between 70 and 99.

Create a deck

To create a deck, you need to provide a name. A deck is created with default fields "Front" and "Back". You may update the deck fields once the deck is created.

curl https://api.recall.cards/v1/decks \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My deck"
  }'

name string required

The name of the deck. Must be between 1 and 60 characters.

settings object, optional

An object containing the settings of the deck.

max_new_reviews_per_day integer, default is 10

The maximum number of new reviews added each day. Fewer are added if many are already due.

target_retention integer, default is 90

The minimum percentage of cards of the deck the user aims to remember at any given time. Must be between 70 and 99.

Returns

Returns the created deck object.

Update a deck

curl https://api.recall.cards/v1/decks/deck_5gvuzRdHW2ac \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New name",
    "settings": {
      "max_new_reviews_per_day": 20,
      "target_retention": 85
    }
  }'

name string required

The name of the deck. Must be between 1 and 60 characters.

settings object, optional

An object containing the settings of the deck.

max_new_reviews_per_day integer, default is 10

The maximum number of new reviews added each day. Fewer are added if many are already due.

target_retention integer, default is 90

The minimum percentage of cards of the deck the user aims to remember at any given time. Must be between 70 and 99.

Returns

Returns the updated deck object.

List all decks

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

limit optional, default is 10

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

starting_after optional

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

Returns

{
  "object": "list",
  "has_more": true,
  "data": [
    // Deck objects...
  ],
}

object string, value is "list"

The type of object returned.

data array

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

curl https://api.recall.cards/v1/decks/deck_5gvuzRdHW2ac \
  -u YOUR_API_KEY:

There are no parameters for this endpoint.

Returns

Returns the deck object.

Delete a deck

Deleting a deck will delete in cascade all its cards, deck fields, card layouts, and card layout fields.

curl https://api.recall.cards/v1/decks/deck_5gvuzRdHW2ac \
  -u YOUR_API_KEY: \
  -X DELETE

There are no parameters for this endpoint.

Returns

{
  "id": "deck_5gvuzRdHW2ac",
  "object": "deck",
  "deleted": true
}

Introduction

Deck fields