Study Plans API

Overview

Study plans are the core organizational unit in Study Sync. They contain collections of learning resources organized for a specific course or topic.

List Study Plans

curl -X GET "https://your-domain.com/api/study-plans?view=public&page=1&limit=9" \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /api/study-plans Get study plans based on view type and filters. Supports optional authentication.

Query Parameters

view

string

default:"public"

Filter by view type:

public - All public study plans
my - User’s own plans and plans shared with them (requires auth)

string

Search query to filter by title, short description, or full description

courseCode

string

Filter by course code (case-insensitive partial match)

sort

string

default:"newest"

Sort order:

newest - Most recently created
popular - Highest instance count
shortest - Fewest resources

page

integer

default:"1"

Page number for pagination

limit

integer

default:"9"

Number of plans per page

Response

plans

array

Array of study plan objects

Show Study Plan Object

_id

string

Unique plan identifier (24-char hex)

title

string

Plan title

shortDescription

string

Brief description

fullDescription

string

Detailed description

courseCode

string

Course identifier (e.g., “CS101”)

isPublic

boolean

Whether plan is publicly visible

resourceIds

array

Array of resource IDs in this plan

createdBy

object

Creator information

Show Creator Object

_id

string

User ID

displayName

string

User’s name

string

User’s email

photoURL

string

Profile photo URL

totalTime

number

Total estimated time in minutes

resourceCount

number

Number of resources in plan

instanceCount

number

Number of active instances

viewCount

number

Total views (public plans only)

createdAt

string

ISO 8601 timestamp

pagination

object

Pagination metadata

Show Pagination Object

Create Study Plan

curl -X POST "https://your-domain.com/api/study-plans" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Introduction to Algorithms",
    "shortDescription": "Learn fundamental algorithms and data structures",
    "fullDescription": "Comprehensive guide covering sorting, searching, and more",
    "courseCode": "CS301",
    "isPublic": true
  }'

POST /api/study-plans Create a new study plan. Requires authentication.

Request Body

title

string

required

Plan title

shortDescription

string

required

Brief description (shown in lists)

courseCode

string

required

Course identifier (e.g., “CS101”)

fullDescription

string

Detailed description (optional)

isPublic

boolean

default:false

Whether plan should be publicly visible

Response

message

string

Success message: “Study plan created successfully”

studyPlan

object

The created study plan object with all fields

Get Study Plan

curl -X GET "https://your-domain.com/api/study-plans/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /api/study-plans/:id Get a specific study plan by ID. Public plans don’t require authentication.

Path Parameters

string

required

Study plan ID (24-character hex string)

Query Parameters

sortBy

string

default:"order"

How to sort resources:

order - Original order from plan
title - Alphabetical by title
duration - By estimated time
type - By resource type

Response

Returns the study plan object with populated resources and additional fields:

resourceIds

array

Full resource objects (not just IDs) in sorted order

totalTime

number

Total estimated time in minutes

resourceCount

number

Number of resources

canEdit

boolean

Whether current user can edit this plan

Update Study Plan

curl -X PUT "https://your-domain.com/api/study-plans/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Advanced Algorithms",
    "isPublic": true,
    "resourceIds": ["507f191e810c19729de860ea", "507f191e810c19729de860eb"]
  }'

PUT /api/study-plans/:id Update a study plan. Requires edit permissions (creator or editor role).

Path Parameters

string

required

Study plan ID

Request Body

All fields are optional. Only include fields you want to update.

title

string

Plan title

shortDescription

string

Brief description

fullDescription

string

Detailed description

courseCode

string

Course code

isPublic

boolean

Public visibility

resourceIds

array

Array of resource IDs (to reorder or modify resources)

Response

message

string

“Study plan updated successfully”

studyPlan

object

Updated study plan object

Delete Study Plan

curl -X DELETE "https://your-domain.com/api/study-plans/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_TOKEN"

DELETE /api/study-plans/:id Delete a study plan. Only the creator can delete.

Path Parameters

string

required

Study plan ID

Response

message

string

“Study plan deleted successfully”

curl -X POST "https://your-domain.com/api/study-plans/507f1f77bcf86cd799439011/share" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role": "editor"
  }'

POST /api/study-plans/:id/share Share a study plan with another user via email. Sends invitation email.

Path Parameters

string

required

Study plan ID

Request Body

string

required

Email address of person to share with

role

string

default:"editor"

Access level:

viewer - Can view only
editor - Can edit and share

Response

message

string

“Study plan shared successfully”

shared

object

Show Shared Access Object

string

Recipient email

role

string

Access role

sharedAt

string

ISO timestamp

Remove Collaborator

curl -X DELETE "https://your-domain.com/api/study-plans/507f1f77bcf86cd799439011/share/[email protected]" \
  -H "Authorization: Bearer YOUR_TOKEN"

DELETE /api/study-plans/:id/share/:userId Remove a collaborator’s access. Can use either user ID or email address.

Path Parameters

string

required

Study plan ID

userId

string

required

User ID (24-char hex) or email address to remove

Response

message

string

“Collaborator removed successfully”

Error Responses

400 Bad Request

{
  "error": "Title, short description, and course code are required"
}

401 Unauthorized

{
  "error": "Authentication required"
}

403 Forbidden

{
  "error": "You do not have permission to edit this study plan"
}

404 Not Found

{
  "error": "Study plan not found"
}

Overview

Endpoints

Overview

List Study Plans

Query Parameters

Response

Create Study Plan

Request Body

Response

Get Study Plan

Path Parameters

Query Parameters

Response

Update Study Plan

Path Parameters

Request Body

Response

Delete Study Plan

Path Parameters

Response

Path Parameters

Request Body

Response

Remove Collaborator

Path Parameters

Response

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

Build docs developers (and LLMs) love

Overview

Endpoints

​Overview

​List Study Plans

​Query Parameters

​Response

​Create Study Plan

​Request Body

​Response

​Get Study Plan

​Path Parameters

​Query Parameters

​Response

​Update Study Plan

​Path Parameters

​Request Body

​Response

​Delete Study Plan

​Path Parameters

​Response

​Share Study Plan

​Path Parameters

​Request Body

​Response

​Remove Collaborator

​Path Parameters

​Response

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

Build docs developers (and LLMs) love

Overview

List Study Plans

Query Parameters

Response

Create Study Plan

Request Body

Response

Get Study Plan

Path Parameters

Query Parameters

Response

Update Study Plan

Path Parameters

Request Body

Response

Delete Study Plan

Path Parameters

Response

Share Study Plan

Path Parameters

Request Body

Response

Remove Collaborator

Path Parameters

Response

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found