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",
  "cards_count": 217,
  "created_at": "2025-11-30T12:34:56Z",
  "name": "My deck",
  "settings": {
    "max_new_cards_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 objectsExpandable

An array of the card layouts objects belonging to the deck. Only included in the response if the expand parameter includes card_layouts.

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 objectsExpandable

An array of the deck fields objects belonging to the deck. Only included in the response if the expand parameter includes deck_fields.

name string

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

settings object

An object containing the settings of the deck.

max_new_cards_per_day integer, default is 10

The maximum number of new cards added to the reviews each day. Less cards 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 50 characters.

settings object, optional

An object containing the settings of the deck.

max_new_cards_per_day integer, default is 10

The maximum number of new cards added to the reviews each day. Less cards 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_cards_per_day": 20,
      "target_retention": 85
    }
  }'

name string, required

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

settings object, optional

An object containing the settings of the deck.

max_new_cards_per_day integer, default is 10

The maximum number of new cards added to the reviews each day. Less cards 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 an deck ID that defines your place in the list.

ending_before optional

A cursor to use in pagination. Similarly to starting_after, ending_before is an deck ID that allows you to fetch deck 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

Delting 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