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,
  },
}

Create a deck

To create a deck, you need to provide a name. You may optionally provide its deck fields and card layouts objects to define the deck's structure in a single call.

Minimal deck creation

A minimal call only requires a name. When deck_fields is omitted, the deck is created with default "Front" and "Back" fields.

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

Deck creation with fields and layouts

You may provide deck_fields and card_layouts to set up your deck's structure in a single call.

You can create deck_fields without providing card_layouts, but you can't create card_layouts without providing deck_fields. When you provide deck_fields without card_layouts, Recall creates the deck's primary card layout automatically: the first field is shown on the front of the card and the remaining fields on the back.

Because every deck field and layout field in this request is created simultaneously, items reference each other with temporary IDs instead of the definitive IDs, which do not exist yet. Each temporary ID must be unique within the request. It is never stored or returned.

curl https://api.recall.cards/v1/decks \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spanish vocabulary",
    "deck_fields": [
      {
        "temporary_id": "spanish",
        "name": "Spanish",
        "type": "plain_text"
      },
      {
        "temporary_id": "english",
        "name": "English",
        "type": "plain_text"
      },
      {
        "temporary_id": "pronunciation",
        "name": "Pronunciation",
        "type": "audio",
        "is_autofill_enabled": true,
        "autofill_type": "text_to_speech",
        "autofill_language_to": "es",
        "autofill_generate_from_deck_fields": ["spanish"]
      }
    ],
    "card_layouts": [
      {
        "card_layout_fields": [
          { "temporary_id": "spanish_line", "deck_field": "spanish", "is_front": true },
          { "deck_field": "pronunciation", "is_front": true, "next_to_card_layout_field": "spanish_line" },
          { "deck_field": "english", "is_front": false }
        ]
      }
    ]
  }'

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
    }
  }'

Returns

Returns the updated deck object.

List all decks

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

Returns

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

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
}