Flashcards

Overview

The Flashcards component automatically generates interactive flashcards from your study materials. It supports multiple card types, spaced repetition learning, and difficulty levels to optimize your study sessions.

Cards are generated in the background after the component is created, and generation waits for materials that are still processing. Learners can start studying in the embed while cards are still being added.

Creating a Flashcards Component

JavaScript

import StudyfetchSDK from '@studyfetch/sdk';

const client = new StudyfetchSDK({
  apiKey: 'your-api-key',
  baseURL: 'https://studyfetchapi.com',
});

const flashcardsComponent = await client.v1.components.create({
  name: 'Biology Flashcards',
  type: 'flashcards',
  config: {
    materials: ['mat-123', 'mat-456'],
    folders: ['folder-789'],
    difficulty: 'mixed',
    totalFlashcards: 30,
    viewMode: 'normal',
    cardTypes: ['BASIC', 'MULTIPLE_CHOICE'],
    model: 'gpt-4o-mini-2024-07-18',
  },
});

console.log('Flashcards component created:', flashcardsComponent._id, flashcardsComponent.componentId);

Python

from studyfetch_sdk import StudyfetchSDK

client = StudyfetchSDK(
    api_key="your-api-key",
    base_url="https://studyfetchapi.com",
)

flashcards_component = client.v1.components.create(
    name="Biology Flashcards",
    type="flashcards",
    config={
        "materials": ["mat-123", "mat-456"],
        "folders": ["folder-789"],
        "difficulty": "mixed",
        "total_flashcards": 30,
        "view_mode": "normal",
        "card_types": ["BASIC", "MULTIPLE_CHOICE"],
        "model": "gpt-4o-mini-2024-07-18",
    },
)

print(f"Flashcards component created: {flashcards_component.api_id} {flashcards_component.component_id}")

Java

import com.studyfetch.javasdk.client.StudyfetchSdkClient;
import com.studyfetch.javasdk.client.okhttp.StudyfetchSdkOkHttpClient;
import com.studyfetch.javasdk.models.v1.components.ComponentResponse;
import com.studyfetch.javasdk.models.v1.components.ComponentCreateParams;
import java.util.List;

public class CreateFlashcardsComponent {
    public static void main(String[] args) {
        StudyfetchSdkClient client = StudyfetchSdkOkHttpClient.builder()
            .fromEnv()
            .baseUrl("https://studyfetchapi.com")
            .build();

        ComponentCreateParams params = ComponentCreateParams.builder()
            .name("Biology Flashcards")
            .type(ComponentCreateParams.Type.FLASHCARDS)
            .config(ComponentCreateParams.Config.FlashcardsConfigDto.builder()
                .materials(List.of("mat-123", "mat-456"))
                .folders(List.of("folder-789"))
                .difficulty(ComponentCreateParams.Config.FlashcardsConfigDto.Difficulty.MIXED)
                .totalFlashcards(30.0)
                .viewMode(ComponentCreateParams.Config.FlashcardsConfigDto.ViewMode.NORMAL)
                .cardTypes(List.of("BASIC", "MULTIPLE_CHOICE"))
                .model("gpt-4o-mini-2024-07-18")
                .build())
            .build();

        ComponentResponse component = client.v1().components().create(params);
        System.out.println("Flashcards component created: " + component._id());
    }
}

C#

using StudyfetchSDK;
using StudyfetchSDK.Models.V1.Components;
using StudyfetchSDK.Models.V1.Components.ComponentCreateParamsProperties.ConfigProperties.FlashcardsConfigDtoProperties;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

public class CreateFlashcardsComponent
{
    public static async Task CreateFlashcards()
    {
        var client = new StudyfetchSDKClient()
        {
            APIKey = Environment.GetEnvironmentVariable("STUDYFETCH_API_KEY"),
            BaseUrl = new Uri("https://studyfetchapi.com")
        };

        var flashcardsComponent = await client.V1.Components.Create(new()
        {
            Name = "Biology Flashcards",
            Type = StudyfetchSDK.Models.V1.Components.ComponentCreateParamsProperties.Type.Flashcards,
            Config = new StudyfetchSDK.Models.V1.Components.ComponentCreateParamsProperties.ConfigProperties.FlashcardsConfigDto()
            {
                Materials = new List<string> { "mat-123", "mat-456" },
                Folders = new List<string> { "folder-789" },
                Difficulty = Difficulty.Mixed,
                TotalFlashcards = 30,
                ViewMode = ViewMode.Normal,
                CardTypes = new List<string> { "BASIC", "MULTIPLE_CHOICE" },
                Model = "gpt-4o-mini-2024-07-18",
            }
        });

        Console.WriteLine($"Flashcards component created: {flashcardsComponent._ID}");
    }
}

Configuration Parameters

name

string · required

Name of the flashcards component

type

string · required

Must be "flashcards"

config

object · required

Flashcards configuration object. Provide at least one material or folder. Unknown keys and values in the wrong case are rejected with 400.

Configuration Properties

These properties go inside config.

materials

array

Material IDs to generate flashcards from. Provide materials, folders, or both.

folders

array

Folder IDs whose materials (including subfolders) flashcards are generated from

difficulty

string · default: medium

Difficulty level of generated cards. Lowercase:

• easy - Basic recall and definitions
• medium - Application and understanding
• hard - Complex analysis and synthesis
• mixed - Combination of all levels

totalFlashcards

number · default: 10

Number of flashcards to generate, from 1 to 50

viewMode

string · default: spaced_repetition

How the embed presents cards:

• spaced_repetition - Show the cards due for review and let learners rate them
• normal - Browse all cards in order

cardTypes

array · default: ["BASIC"]

Types of flashcards to generate:

• BASIC - Front and back
• MULTIPLE_CHOICE - Question with answer options
• FILL_IN_THE_BLANK - Sentence with a missing term
• CLOZE - Text with hidden passages

model

string · default: gpt-4o-mini-2024-07-18

AI model used to generate the flashcards

learningSteps

string

Accepted and stored, but not currently used. Learning steps are fixed at 1 minute, 10 minutes, and 1 day.

maxReviewInterval

number

Accepted and stored, but not currently used

Response

{
  "_id": "6650f1c2a9b3e4d5f6a7b8c9",
  "componentId": "flashcards_V1StGXR8_Z",
  "name": "Biology Flashcards",
  "type": "flashcards",
  "status": "active",
  "origin": "api",
  "organization": "64f0a1b2c3d4e5f6a7b8c9d0",
  "materials": ["mat-123", "mat-456"],
  "folders": ["folder-789"],
  "config": {
    "materials": ["mat-123", "mat-456"],
    "folders": ["folder-789"],
    "difficulty": "mixed",
    "totalFlashcards": 30,
    "viewMode": "normal",
    "cardTypes": ["BASIC", "MULTIPLE_CHOICE"],
    "model": "gpt-4o-mini-2024-07-18"
  },
  "usageCount": 0,
  "createdAt": "2026-10-06T10:00:00.000Z",
  "updatedAt": "2026-10-06T10:00:00.000Z"
}

The component is active as soon as it is created, while cards are still being generated. Generation progress is reported as generationStatus when you read the cards.

Embedding This Component

Once you've created a Flashcards component, you can embed it on your website using the embedding API. The component must be active. Spaced-repetition progress is stored per userId, so generate each learner's embed with their own userId.

Generate Embed URL

JavaScript

const embedResponse = await client.v1.components.generateEmbed(flashcardsComponent._id, {
  // User tracking
  userId: 'user-456',
  studentName: 'Jane Smith',  // Student name for display
  groupIds: ['class-101', 'class-102'],
  sessionId: 'session-789',

  // Dimensions
  width: '100%',
  height: '500px',
});

console.log(embedResponse.embedUrl);

Python

embed_response = client.v1.components.generate_embed(
    flashcards_component.api_id,
    user_id="user-456",
    student_name="Jane Smith",  # Student name for display
    group_ids=["class-101", "class-102"],
    session_id="session-789",
    width="100%",
    height="500px",
)

print(embed_response.embed_url)

Java

import com.studyfetch.javasdk.models.v1.components.ComponentGenerateEmbedParams;
import com.studyfetch.javasdk.models.v1.components.ComponentGenerateEmbedResponse;

ComponentGenerateEmbedParams params = ComponentGenerateEmbedParams.builder()
    .id(flashcardsComponent._id())
    // User tracking
    .userId("user-456")
    .studentName("Jane Smith")  // Student name for display
    .groupIds(List.of("class-101", "class-102"))
    .sessionId("session-789")

    // Dimensions
    .width("100%")
    .height("500px")
    .build();

ComponentGenerateEmbedResponse embedResponse = client.v1().components()
    .generateEmbed(params);

System.out.println(embedResponse.embedUrl());

C#

using StudyfetchSDK;
using StudyfetchSDK.Models.V1.Components;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

public class GenerateFlashcardsEmbed
{
    public static async Task GenerateEmbed(string flashcardsComponentId)
    {
        var client = new StudyfetchSDKClient()
        {
            APIKey = Environment.GetEnvironmentVariable("STUDYFETCH_API_KEY"),
            BaseUrl = new Uri("https://studyfetchapi.com")
        };

        var embedResponse = await client.V1.Components.GenerateEmbed(new()
        {
            ID = flashcardsComponentId,
            UserID = "user-456",
            StudentName = "Jane Smith",  // Student name for display
            GroupIDs = new List<string> { "class-101", "class-102" },
            SessionID = "session-789",
            Width = "100%",
            Height = "500px"
        });

        Console.WriteLine($"Embed URL: {embedResponse.EmbedURL}");
        Console.WriteLine($"Token: {embedResponse.Token}");
    }
}

The response contains embedUrl, token, expiresAt, componentId (the component's _id), componentType, and options (width and height, defaulting to 100% and 600px).

The flashcards embed doesn't use any features settings. How it presents cards comes from the component's viewMode.

Embed in Your HTML

Use the embedUrl from the response as the iframe source. The host can differ per organization, so don't build the URL yourself.

<iframe
  src="EMBED_URL_FROM_RESPONSE"
  width="100%"
  height="500px"
  frameborder="0"
  style="border: 1px solid #e5e5e5; border-radius: 8px;">
</iframe>

Reading Cards and Progress

To work with cards from your server, send an action to POST /api/v1/components/{id}/interact, where {id} is the component's _id:

rating is 0 (Again), 1 (Hard), 2 (Good), or 3 (Easy). generationStatus reports totalRequested, totalGenerated, inProgress, complete, failed, and waitingForMaterials while cards are being generated (or before any exist). It is null once generation has finished and cards exist.

The SDKs' interact methods don't send a request body yet, so use cURL or an HTTP client.

curl -X POST "https://studyfetchapi.com/api/v1/components/6650f1c2a9b3e4d5f6a7b8c9/interact" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "action": "get_due", "userId": "user-456", "limit": 10 }'

React Native

The React Native SDK (@studyfetch/react-native-sdk) renders Flashcards natively with embed tokens instead of an iframe. Import it from @studyfetch/react-native-sdk/flashcards and wrap your app in EmbedTokenProvider with a getToken function that asks your backend to mint an embed token for a component.

import { EmbedTokenProvider } from '@studyfetch/react-native-sdk';
import { StudyFetchFlashcards, useFlashcards } from '@studyfetch/react-native-sdk/flashcards';

// Full flashcards UI with Again / Hard / Good / Easy rating
<EmbedTokenProvider getToken={fetchToken}>
  <StudyFetchFlashcards componentId="flashcards_V1StGXR8_Z" userId="user-456" mode="due" />
</EmbedTokenProvider>

// Headless: build your own UI
const { cards, current, stats, generating, rate, next, prev, loadMore } = useFlashcards({
  componentId: 'flashcards_V1StGXR8_Z',
  userId: 'user-456',
});

• mode is all (default) or due.
• Pass a userId; ratings are saved per user.
• generating is true while cards are still being created.