Skip to main content

​
Overview

Resources are learning materials within study plans. Supported types include YouTube videos, playlists, PDFs, articles, Google Drive files, and custom links.

​
Resource Types

  • youtube-video - YouTube video with auto-fetched metadata
  • youtube-playlist - Expands into individual video resources
  • pdf - PDF document with page count
  • article - Web article with estimated reading time
  • google-drive - Google Drive file
  • custom-link - Generic URL

​
List Resources

curl -X GET "https://your-domain.com/api/resources?studyPlanId=507f1f77bcf86cd799439011&sortBy=order" \
  -H "Authorization: Bearer YOUR_TOKEN"
GET /api/resources Get resources for a specific study plan.

​
Query Parameters

​
studyPlanId
string
required
Study plan ID to fetch resources for
​
sortBy
string
default:"order"
Sort order:
  • order - Plan’s original order
  • title - Alphabetical by title
  • duration - By estimated time
  • type - By resource type

​
Response

​
resources
array
Array of resource objects
​
sortBy
string
Applied sort order

​
Create Resource

curl -X POST "https://your-domain.com/api/resources" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }'
POST /api/resources Create a new resource. Type is auto-detected from URL if not specified.

​
Request Body

​
url
string
required
Resource URL
​
type
string
Resource type (auto-detected if omitted):
  • youtube-video - Single YouTube video
  • youtube-playlist - YouTube playlist (creates multiple resources)
  • pdf - PDF document
  • article - Web article
  • google-drive - Google Drive file
  • custom-link - Generic link
​
title
string
Resource title (auto-fetched for YouTube, required for others)

​
YouTube-specific

​
url
string
required
YouTube video or playlist URL. Metadata is automatically fetched.

​
PDF-specific

​
title
string
required
PDF title
​
pages
number
required
Number of pages
​
minsPerPage
number
default:3
Estimated minutes per page

​
Article-specific

​
title
string
required
Article title
​
estimatedMins
number
required
Estimated reading time in minutes
​
title
string
Resource title (defaults to URL if omitted)
​
estimatedMins
number
Optional estimated time

​
Response

​
Single Resource

​
message
string
“Resource created successfully” or “Resource already exists”
​
resource
object
The created resource object
​
isNew
boolean
Whether resource was newly created or already existed

​
YouTube Playlist

​
message
string
Summary of created/existing resources
​
resources
array
Array of video resource objects
​
newCount
number
Number of newly created resources
​
existingCount
number
Number of resources that already existed

​
Get Resource

curl -X GET "https://your-domain.com/api/resources/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_TOKEN"
GET /api/resources/:id Get a specific resource by ID.

​
Path Parameters

​
id
string
required
Resource ID

​
Response

Returns the resource object.

​
Get Bulk Resources

curl -X GET "https://your-domain.com/api/resources/bulk?ids=507f1f77bcf86cd799439011,507f1f77bcf86cd799439012" \
  -H "Authorization: Bearer YOUR_TOKEN"
GET /api/resources/bulk Get multiple resources by IDs.

​
Query Parameters

​
ids
string
required
Comma-separated list of resource IDs

​
Response

Returns array of resource objects with calculated totalTime field.

​
Update Resource

curl -X PUT "https://your-domain.com/api/resources/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "metadata": { "estimatedMins": 15 }
  }'
PUT /api/resources/:id Update a resource. Requires edit permissions on the associated study plan.

​
Path Parameters

​
id
string
required
Resource ID

​
Request Body

​
title
string
Resource title
​
url
string
Resource URL
​
description
string
Resource description
​
metadata
object
Resource metadata
​
order
number
Display order

​
Response

​
message
string
“Resource updated successfully”
​
resource
object
Updated resource object

​
Delete Resource

curl -X DELETE "https://your-domain.com/api/resources/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_TOKEN"
DELETE /api/resources/:id Delete a resource. Only the study plan creator can delete. Also removes the resource from the study plan’s resourceIds array.

​
Path Parameters

​
id
string
required
Resource ID

​
Response

​
message
string
“Resource deleted successfully”

​
Automatic Metadata Fetching

​
YouTube Videos

When creating a YouTube video resource, the API automatically:
  1. Extracts the video ID from the URL
  2. Fetches metadata using YouTube Data API
  3. Stores title, duration, thumbnail, and video ID

​
YouTube Playlists

When creating a YouTube playlist resource:
  1. Extracts playlist ID from URL
  2. Fetches all videos in the playlist
  3. Creates individual youtube-video resources for each
  4. Returns array of created resources

​
Duplicate Detection

The API checks for existing resources by URL to prevent duplicates:
  • Single resource: Returns existing resource if URL matches
  • Playlist: Reuses existing videos, only creates new ones

​
Error Responses

​
400 Bad Request

{
  "error": "URL is required"
}

{
  "error": "Title and pages are required for PDF"
}

​
403 Forbidden

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

​
404 Not Found

{
  "error": "Resource not found"
}

​
500 Internal Server Error

{
  "error": "Failed to fetch video metadata"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us