Card variants

A card variant is a card in a given card layout.

The spaced repetition algorithm lives at the card variant level. Each variant carries its own review date, learning stage and difficulty.

The next_review_at attribute on the card object is the earliest next_review_at across the card's variants.

Endpoints

GET    /v1/card_variants                  # List all card variants
GET    /v1/card_variants/:id              # Get a card variant
POST   /v1/card_variants/:id/schedule     # Schedule a card variant
POST   /v1/card_variants/:id/snooze       # Snooze a card variant
POST   /v1/card_variants/:id/suspend      # Suspend a card variant
POST   /v1/card_variants/:id/unsuspend    # Unsuspend a card variant

The card variant object

{
  "id": "variant_pQ3nRb7KcxT2",
  "object": "card_variant",
  "card": "card_lBsPlNZe4356",
  "card_layout": "layout_yT9ktMcdzg4e",
  "difficulty": "medium",
  "interval": 12,
  "next_review_at": "2025-12-01T15:00:00Z",
  "stage": "young",
}
id string

Unique identifier for the card variant.

object string, value is "card_variant"

The type of the object.

card stringExpandable

The ID of the card the variant belongs to. When card is included in expand, this is a card object instead.

card_layout stringExpandable

The ID of the card layout the variant presents the card in. When card_layout is included in expand, this is a card layout object instead.

difficulty nullable enum

How hard the variant currently is to remember. Computed by the scheduling algorithm from your review grades. null until the variant has been reviewed.

easy
The variant is well remembered and its reviews can be spaced out quickly.
medium
The variant requires a regular review pace.
hard
The variant is hard to remember and needs frequent reviews.
very_hard
The variant is at the maximum difficulty and has been forgotten at least 5 times.
interval nullable integer

The number of days between the variant's last review and its next scheduled review, computed when the variant is reviewed. Snoozing moves next_review_at without changing it. null until a review sets an interval.

next_review_at nullable string

The date and time the variant is scheduled for review, or null when the variant is unscheduled or suspended. A value in the past means the variant is due now. RFC 3339–formatted UTC datetime.

stage enum

The learning stage of the variant.

unscheduled
The variant has not entered the review queue yet.
learning
The variant is being learned, with reviews in short steps.
relearning
The variant was forgotten during a review and is being relearned in short steps.
young
The variant graduated from learning and its interval is below 21 days.
mature
The variant graduated from learning and its interval is 21 days or more.
suspended
The variant is excluded from reviews and scheduling until unsuspended.

List all card variants

curl "https://api.recall.cards/v1/card_variants?card=card_lBsPlNZe4356" \
  -u YOUR_API_KEY:
card string

Filter the variants by the ID of the card they belong to.

deck string

Filter the variants by the ID of the deck their card belongs to.

stage string

Filter the variants by stage, for example stage=suspended.

difficulty string

Filter the variants by difficulty label, for example difficulty=very_hard. Variants that have never been reviewed have a null difficulty and never match this filter.

limit optional, default is 10

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

starting_after optional

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

Returns

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

The type of object returned.

data array

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

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

There are no parameters for this endpoint.

Returns

Returns the card variant object.

Schedule a card variant

Puts an unscheduled variant in the review queue. The variant enters the learning stage and becomes due immediately.

curl https://api.recall.cards/v1/card_variants/variant_pQ3nRb7KcxT2/schedule \
  -u YOUR_API_KEY: \
  -X POST

There are no parameters for this endpoint.

Only variants in the unscheduled stage can be scheduled. Scheduling a variant in any other stage returns an invalid_request error.

Note that Recall also schedules new cards automatically over time, respecting each deck's max_new_reviews_per_day setting. Use this endpoint when you want a specific variant to enter the review queue now.

Returns

Returns the updated card variant object.

Snooze a card variant

Postpones a variant's next review to tomorrow at 5:00 in your time zone. The variant's stage, interval and difficulty are unchanged: snoozing only moves the review date.

curl https://api.recall.cards/v1/card_variants/variant_pQ3nRb7KcxT2/snooze \
  -u YOUR_API_KEY: \
  -X POST

There are no parameters for this endpoint.

Only scheduled variants (in the learning, relearning, young or mature stage) can be snoozed. Snoozing an unscheduled or suspended variant returns an invalid_request error.

Returns

Returns the updated card variant object.

Suspend a card variant

Excludes a variant from reviews and scheduling. The variant enters the suspended stage and its next_review_at becomes null, until it is unsuspended.

curl https://api.recall.cards/v1/card_variants/variant_pQ3nRb7KcxT2/suspend \
  -u YOUR_API_KEY: \
  -X POST

There are no parameters for this endpoint.

Suspending a variant that is already suspended returns an invalid_request error.

Returns

Returns the updated card variant object.

Unsuspend a card variant

Lifts a variant's suspension. The variant returns to the unscheduled stage and keeps its review history: schedule it again, or let Recall's automatic scheduling pick it up, to resume reviews.

curl https://api.recall.cards/v1/card_variants/variant_pQ3nRb7KcxT2/unsuspend \
  -u YOUR_API_KEY: \
  -X POST

There are no parameters for this endpoint.

Only variants in the suspended stage can be unsuspended. Unsuspending a variant in any other stage returns an invalid_request error.

Returns

Returns the updated card variant object.