API Docs

Authentication

All endpoints are secured and require authentication. The API uses API keys that are strictly assigned to specific projects. You must provide your project's valid API key in the standard Authorization header as a Bearer token:

Authorization: Bearer <your-api-key>

Data Model and Relationships

Our API revolves around a clear and structured hierarchy designed to accurately model learning activities. This structure ensures that all learning progress is precisely tracked and can be queried efficiently:

• Learner (1 to N Collections) – represents an individual user in your system. Each Learner can have multiple separate learning Collections (e.g., different courses, subjects, or languages they are currently studying).

• Learner Collection (1 to N Items) – serves as a distinct container for learning materials. Each Collection consists of numerous Items. For instance, a Collection might be "Spanish Vocabulary," and the Items would be the individual flashcards or words being mapped to that vocabulary.

• Collection Item (1 to N Reviews) – the smallest discrete unit of knowledge (like a single flashcard). Over time, a Learner will review this Item multiple times. Each interaction is recorded as a formal Review, which informs the spaced repetition algorithm (such as SM-20) calculation of when the Item should ideally be shown next to maximize retention.

• Item Review – a single logged interaction event where a Learner grades their memory recall of a specific Collection Item. It records the grade and the exact date to help the algorithm calculate the optimal time for the next review.

External Identifiers

To ensure seamless synchronization and avoid complex ID mappings on your end, our API relies entirely on the unique identifiers originating directly from your (the client's) system. You do not need to store or keep track of our internal database IDs.

Whenever you make requests to log learning data, create reviews, or query algorithmic progress, you will reference these core entities utilizing identifiers uniformly denoted by the ext prefix:

• extLearnerId: The unique integer identifier for a Learner within your application (e.g., your internal User ID).
• extCollectionId: The unique integer identifier for a specific set of learning materials in your system (e.g., a Course ID, Deck ID, or Module ID).
• extItemId: The unique integer identifier for a single piece of knowledge in your system (e.g., a Flashcard ID, Question ID, or Concept ID).

SM-20 Algorithm Integration

Our system is exclusively powered by the SM-20 spaced repetition algorithm. The API exposes several dedicated endpoints to leverage this engine:

• Real-time Reviews: Submitting a single item review processes the grade and immediately returns the optimal predicted interval for the next repetition.
• Weights Optimization: You can trigger an optimization process that deeply analyzes a Learner's specific collection history to recalculate and fine-tune SM-20 weights, naturally adapting the algorithm to their personal memory traits over time.
• Bulk History Imports: If you are migrating existing learners, you can asynchronously import substantial datasets of historical reviews using a CSV file. The API provides a parallel status endpoint to track the metrics and progress of these ongoing background imports.