Skip to main content

​
Overview

Instances represent a user’s active enrollment in a study plan. Each instance has its own schedule, reminders, and tracks completion independently. When created, instances snapshot the study plan’s resources at that moment.

​
List Instances

curl -X GET "https://your-domain.com/api/instances?status=active" \
  -H "Authorization: Bearer YOUR_TOKEN"
GET /api/instances Get user’s study plan instances. Requires authentication.

​
Query Parameters

​
status
string
Filter by status:
  • active - Currently active instances
  • completed - Finished instances
  • paused - Paused instances
​
studyPlanId
string
Filter by specific study plan ID

​
Response

​
instances
array
Array of instance objects

​
Create Instance

curl -X POST "https://your-domain.com/api/instances" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "studyPlanId": "507f1f77bcf86cd799439011",
    "startDate": "2026-03-10T00:00:00Z",
    "endDate": "2026-04-10T00:00:00Z",
    "reminderTime": "09:00",
    "resourceSchedule": []
  }'
POST /api/instances Create a new study plan instance. Snapshots the plan’s resources at creation time.

​
Request Body

​
studyPlanId
string
required
Study plan ID to create instance from
​
startDate
string
required
Start date (ISO 8601 format)
​
endDate
string
required
End date/deadline (ISO 8601 format). Must be after startDate.
​
reminderTime
string
default:"09:00"
Daily reminder time in HH:MM format
​
resourceSchedule
array
Optional resource scheduling information

​
Response

​
message
string
“Instance created successfully”
​
instance
object
The created instance object

​
Get Instance

curl -X GET "https://your-domain.com/api/instances/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_TOKEN"
GET /api/instances/:id Get a specific instance with full details including resources and progress.

​
Path Parameters

​
id
string
required
Instance ID

​
Response

Returns the instance object with additional fields:
​
resources
array
Array of resource objects with completion status
​
studyPlan
object
Full study plan details including resources

​
Update Instance

curl -X PUT "https://your-domain.com/api/instances/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "notes": "Finished ahead of schedule!",
    "reminderEnabled": false
  }'
PUT /api/instances/:id Update an instance. Only the owner can update.

​
Path Parameters

​
id
string
required
Instance ID

​
Request Body

All fields are optional. Only include fields to update.
​
startDate
string
Start date (ISO 8601)
​
endDate
string
End date (ISO 8601)
​
status
string
Status: active, completed, or paused
​
progress
number
Progress percentage (0-100)
​
reminderTime
string
Reminder time (HH:MM)
​
reminderEnabled
boolean
Enable/disable reminders
​
customReminders
array
Custom reminder schedule
​
notes
string
Instance notes
​
resourceNotes
object
Per-resource notes as key-value pairs: { resourceId: "note text" }
​
customTitles
object
Custom resource titles
​
resourceIds
array
Reorder/modify instance resources (uses snapshotResourceIds)

​
Response

​
message
string
“Instance updated successfully”
​
instance
object
Updated instance object

​
Delete Instance

curl -X DELETE "https://your-domain.com/api/instances/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_TOKEN"
DELETE /api/instances/:id Delete an instance. Only the owner can delete.

​
Path Parameters

​
id
string
required
Instance ID

​
Response

​
message
string
“Instance deleted successfully”

​
Key Concepts

​
Resource Snapshotting

When an instance is created, it snapshots the study plan’s resources at that moment:
  • Stored in snapshotResourceIds field
  • Independent of future study plan changes
  • Ensures instance stability even if plan is modified

​
Progress Tracking

Progress is tracked globally per user per resource:
  • Completing a resource in one instance marks it complete everywhere
  • Use the User Progress API to manage completion status
  • Instance tracks which resources are completed via completedResources array

​
Automatic Updates

The API automatically calculates:
  • totalTime and completedTime based on resource metadata
  • resourcePercent and timePercent for progress tracking
  • remainingTime for scheduling
  • lastAccessedAt when instance is viewed

​
Error Responses

​
400 Bad Request

{
  "error": "End date must be after start date"
}

​
403 Forbidden

{
  "error": "You do not have permission to access this instance"
}

​
404 Not Found

{
  "error": "Instance not found"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us