Cards

This object represents a card in Recall. All cards belong to a deck and are structured in its deck fields.

Endpoints

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

The card object

{
  "id": "card_lBsPlNZe4356",
  "object": "card",
  "autofill": null,
  "content": {
    "french_word": "Bonjour",
    "translation": "Hello",
    "sentence": "<p><strong>Bonjour</strong>, comment ça va?</p>",
    "sentence_translation": "<p><strong>Hello</strong>, how are you?</p>",
  },
  "created_at": "2025-11-30T12:34:56Z",
  "deck_id": "deck_5gvuzRdHW2ac",
  "next_review_at": "2025-12-01T12:34:56Z",
}

id string

The ID of the card.

object string, value is "card"

The type of the object.

autofill nullable object

Summary of the AI Autofill state for this card, or null if no field on this card was ever scheduled for autofill. See AI Autofill for more details.

content object

Object containing the values of the content of the card for each deck field. The keys of the object are the deck_field.key values. Learn more about keys in the deck fields documentation.

created_at string

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

deck_id string

The ID of the deck the card belongs to.

next_review_at string

The date and time the card is scheduled for review. RFC 3339–formatted UTC datetime.

Because decks fields can always be created, deleted or renamed (which updates their key values), it is recommend to always fetch them before creating or updating cards.

Create a card

curl https://api.recall.cards/v1/cards \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "deck_id": "deck_5gvuzRdHW2ac",
    "content": {
      "french_word": "Bonjour",
      "translation": "Hello",
      "sentence": "<p><strong>Bonjour</strong>, comment ça va?</p>",
      "sentence_translation": "<p><strong>Hello</strong>, how are you?</p>"
    }
  }'

deck_id string required

The ID of the deck the card belongs to.

content object required

Object containing the values of the content of the card for each deck field. The keys of the object are the deck_field.key values. The validation of the content values depends on the deck field types. Refer to the deck fields types for more details. It will also validate that the content of the card showed in the front side of the card in the primary layout has at least a value, or will be AI generated on creation.

trigger_autofill boolean, default is true

Whether to trigger AI Autofill for fields that have it enabled and whose source fields have values. AI Autofill runs asynchronously after the card is created. See AI Autofill object. Fields that themselves depend on AI-generated fields will also be successively enriched. Fields whose value is explicitly provided in content are never scheduled for generation; your value prevails.

The edition of image and audio fields in the cards content is not supported in the API at the moment.

Update a card

curl https://api.recall.cards/v1/cards/card_5gvuzRdHW2ac \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "sentence": "<p><strong>Bonjour</strong>, je voudrais un croissant.</p>"
    }
  }'

content object

Object containing the values of the content of the card for each deck field. The keys of the object are the deck_field.key values. Updates are partial: keys present in the request are updated, keys absent are left unchanged, and keys set to null are cleared. The validation of the content values depends on the deck field types. Refer to the deck fields types for more details. It will also validate that the content of the card showed in the front side of the card in the primary layout has at least a value, or will be AI generated on update.

trigger_autofill boolean, default is true

Whether to trigger AI Autofill for fields that have it enabled and whose source fields are being updated. AI Autofill runs asynchronously after the card is updated. See AI Autofill object. Fields that themselves depend on AI-generated fields will also be successively enriched. Fields whose value is explicitly provided in content in this request are not scheduled for generation.

Returns

Returns the updated card object.

AI Autofill status

When you create or update a card with trigger_autofill: true (the default), Recall runs asynchronously AI generation for all fields that:

Have AI Autofill enabled
Have source fields with values
Do not have a value explicitly provided in the request

Chained generation may also happen if a field depends on other AI-generated fields.

When AI Autofill has been triggered for a card, the autofill object is updated to reflect the status of the generation. It is null if no field's value was ever generated with AI Autofill.

{
  "id": "card_lBsPlNZe4356",
  "object": "card",
  "autofill": {
    "status": "pending",
    "fields": {
      "illustration": { "status": "pending" },
      "pronunciation": { "status": "failed" }
    }
  },
  "content": {
    "french_word": "Bonjour",
    "translation": "Hello",
    "illustration": null,
    "pronunciation": null,
  },
  // ...
}

status enum

Card-level rollup of every scheduled field.

pending

At least one scheduled field is still being generated.

complete

All scheduled fields succeeded.

failed

All scheduled fields failed.

partial

All scheduled fields reached a terminal state, but at least one succeeded and at least one failed.

fields array of objects

Per-field state. Keys are deck_field.key values. Only fields that were scheduled for autofill appear in this object.

status enum

State of the field.

pending

Generation is queued or in progress. The field's value in content is null.

complete

Generation succeeded. The field's value in content is populated.

failed

Generation exhausted its retries. The field's value in content remains null.

List all cards

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

deck_id string

Filter the cards by the ID of the deck the card belongs to.

limit optional, default is 10

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

starting_after optional

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

Returns

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

object string, value is "list"

The type of object returned.

data array

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

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

There are no parameters for this endpoint.

Returns

Returns the card object.

Delete a card

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

There are no parameters for this endpoint.

Returns

{
  "id": "card_5gvuzRdHW2ac",
  "object": "card",
  "deleted": true
}

Deck fields

Card layouts