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/batch   # Create multiple cards
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": "deck_5gvuzRdHW2ac",
  "next_review_at": "2025-12-01T12:34:56Z",
}

Because deck fields can always be created, deleted or renamed (which updates their key values), it is recommended 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": "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>"
    }
  }'

Batch create cards

Create several cards in a deck in a single request.

All cards in a batch belong to the same deck: provide the deck once, and the cards in the data array. You can create up to 100 cards per request.

The batch is validated as a whole. If any card is invalid (for example an unknown field key, or a missing front value), the entire batch is rejected and no card is created. Duplicate cards are the only exception: instead of failing the request, they are skipped and reported in the response.

A card is considered a duplicate when its front side in the primary layout matches another card. The check runs against both the cards already in the deck and the cards in the same batch.

curl https://api.recall.cards/v1/cards/batch \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "deck": "deck_5gvuzRdHW2ac",
    "data": [
      { "content": { "french_word": "Bonjour", "translation": "Hello" } },
      { "content": { "french_word": "Merci", "translation": "Thank you" } }
    ]
  }'

The total number of cards in the deck (existing cards plus the batch) cannot exceed the per-deck limit of 5,000 cards. If it would, the whole batch is rejected.

Returns

{
  "object": "list",
  "data": [
    // Created card objects, in the order they appear in the request (skipped duplicates excluded)
  ],
  "skipped": [
    { "index": 3, "reason": "duplicate" }
  ]
}

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

Returns

Returns the updated card object.

The AI Autofill object

When you create or update a card with trigger_autofill: true (the default), Recall asynchronously runs 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.

Generation draws from your plan's AI Autofill quota (and image generation credits for image fields). Fields that would exceed your remaining quota are skipped and stay empty; the card itself is still created or updated.

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

List all cards

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

Returns

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

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
}