Skip to main content

​
Overview

The Materials API provides endpoints for managing educational resources including documents, slides, datasets, videos, and links. Materials support search, tagging, and access logging.

​
Material Object

​
id
string
Unique material identifier
​
title
string
Material title
​
description
string
Material description
​
format
string
Format type: document, slide, dataset, video, or link
​
file
string
Uploaded file name (for non-link materials)
​
linkUrl
string
External URL (for link-type materials)
​
visibility
string
Visibility level: institution, course, group, or public
​
courseCode
string
Associated course code
​
tags
array
Array of tags for categorization
​
keywords
string
Searchable keywords
​
searchTerms
string
Combined search index field (title + description + keywords)
​
uploader
string
User ID of material uploader
​
created
string
ISO 8601 timestamp of creation
​
updated
string
ISO 8601 timestamp of last update

​
List Materials

Search and filter materials with pagination.

​
Request

curl -X GET "https://your-domain.com/api/materials?q=machine+learning&format=document&page=1&perPage=30" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
​
q
string
Search query (searches title, description, keywords)
​
format
string
Filter by format: document, slide, dataset, video, or link
​
tags
array
Filter by tags (can be multiple)
​
visibility
string
Filter by visibility level
​
courseCode
string
Filter by course code
​
contributorId
string
Filter by uploader user ID
​
page
number
default:"1"
Page number for pagination
​
perPage
number
default:"30"
Number of materials per page

​
Response

{
  "items": [
    {
      "id": "MATERIAL_ID",
      "collectionId": "materials_collection_id",
      "collectionName": "materials",
      "title": "Introduction to Machine Learning",
      "description": "Lecture notes covering basic ML concepts",
      "format": "document",
      "file": "ml_intro.pdf",
      "linkUrl": "",
      "visibility": "public",
      "courseCode": "CS101",
      "tags": ["machine-learning", "intro"],
      "keywords": "ML, AI, algorithms",
      "searchTerms": "introduction to machine learning lecture notes ml ai algorithms",
      "uploader": "USER_ID",
      "created": "2026-02-01 00:00:00.000Z",
      "updated": "2026-02-01 00:00:00.000Z",
      "expand": {
        "uploader": {
          "id": "USER_ID",
          "username": "professor",
          "email": "[email protected]"
        }
      }
    }
  ],
  "total": 25,
  "page": 1,
  "perPage": 30
}

​
Get Material

Retrieve a single material by ID. Automatically logs the view.

​
Request

curl -X GET "https://your-domain.com/api/materials/{materialId}" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

​
Response

{
  "id": "MATERIAL_ID",
  "collectionId": "materials_collection_id",
  "collectionName": "materials",
  "title": "Introduction to Machine Learning",
  "description": "Lecture notes covering basic ML concepts",
  "format": "document",
  "file": "ml_intro.pdf",
  "linkUrl": "",
  "visibility": "public",
  "courseCode": "CS101",
  "tags": ["machine-learning", "intro"],
  "keywords": "ML, AI, algorithms",
  "searchTerms": "introduction to machine learning lecture notes ml ai algorithms",
  "uploader": "USER_ID",
  "created": "2026-02-01 00:00:00.000Z",
  "updated": "2026-02-01 00:00:00.000Z",
  "expand": {
    "uploader": {
      "id": "USER_ID",
      "username": "professor"
    }
  }
}
Viewing a material automatically creates:
  • A material_access_log entry with action view
  • An analytics_event with name material_view

​
Upload Material

Create a new material with file upload.

​
Request

curl -X POST "https://your-domain.com/api/materials" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -F "title=My Course Notes" \
  -F "description=Notes from today's lecture" \
  -F "file=@/path/to/notes.pdf"
​
title
string
required
Material title
​
description
string
Material description
​
file
file
required
File to upload

​
Response

{
  "id": "MATERIAL_ID",
  "collectionId": "materials_collection_id",
  "collectionName": "materials",
  "title": "My Course Notes",
  "description": "Notes from today's lecture",
  "format": "document",
  "file": "notes_abc123.pdf",
  "visibility": "public",
  "uploader": "USER_ID",
  "created": "2026-03-03 12:00:00.000Z",
  "updated": "2026-03-03 12:00:00.000Z"
}
Note: The current implementation creates materials with default format=document and visibility=public. For more control, use PocketBase collection API directly.

​
Download Material

Download the file associated with a material.

​
Request

curl -X GET "https://your-domain.com/api/materials/{materialId}/download" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -O

​
Response

Returns the file with appropriate Content-Type and Content-Disposition headers. Downloading a material automatically creates:
  • A material_access_log entry with action download
  • An analytics_event with name material_download

​
Update Material

Update material metadata. Uses PocketBase collection API.

​
Request

curl -X PATCH "https://your-domain.com/api/collections/materials/records/{id}" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "description": "Updated description",
    "tags": ["new-tag", "another-tag"],
    "visibility": "course",
    "courseCode": "CS202"
  }'
​
title
string
Updated title
​
description
string
Updated description
​
tags
array
Updated tags
​
visibility
string
Updated visibility level
​
courseCode
string
Updated course code
​
keywords
string
Updated keywords

​
Response

{
  "id": "MATERIAL_ID",
  "title": "Updated Title",
  "description": "Updated description",
  "tags": ["new-tag", "another-tag"],
  "visibility": "course",
  "courseCode": "CS202",
  "updated": "2026-03-03 13:00:00.000Z"
}

​
Delete Material

Delete a material. Uses PocketBase collection API.

​
Request

curl -X DELETE "https://your-domain.com/api/collections/materials/records/{id}" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

​
Response

HTTP 204 No Content

​
Material Formats

Supported material formats:
  • document - PDF, Word, text documents
  • slide - Presentation slides
  • dataset - Data files, CSV, spreadsheets
  • video - Video files or links
  • link - External URL (use linkUrl field instead of file)

​
Visibility Levels

  • public - Accessible to everyone
  • institution - Accessible to institution members
  • course - Accessible to specific course members
  • group - Accessible to specific group members

​
Access Logging

All material views and downloads are logged in the material_access_logs collection: 
curl -X GET "https://your-domain.com/api/collections/material_access_logs/records?filter=material='MATERIAL_ID'" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
Each log entry includes:
  • material - Material ID
  • user - User who accessed the material
  • action - Either view or download
  • created - Timestamp of access
Materials include a computed searchTerms field that combines title, description, and keywords. The search is case-insensitive and searches across all these fields: 
curl -X GET "https://your-domain.com/api/materials?q=machine+learning" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
This searches for “machine learning” in titles, descriptions, and keywords.

Build docs developers (and LLMs) love

Get started for freeTalk to us