REST API

Table of Contents

Overview

The Design and Architecture page describes the anatomy of a request/response pair as well as how the API uses OAuth to authenticate users.

Realms

Realms are entities that have controllable privacy settings. Many objects can belong to any realm.

Resource Description URLs
District Districts are groups of independent schools that do not share a common system (e.g. SIS)
School Schools are the most basic groupings of courses, groups, and users. All courses/users are required to have unique usernames, course IDs, and School User IDs throughout the entire school.
  • schools
  • schools/{id}
Building Buildings (AKA campuses), are further separations of courses, groups, and users that all belong to the same system.
  • schools/{id}/buildings
User Each account corresponds to a user object.
  • users
  • users/{id}
Group Groups are non-academic versions of course sections; they can hold members, events, documents, etc.
  • groups
  • groups/{id}
Course Courses are simply containers for course sections. Objects cannot belong to courses; they can only belong to course sections.
  • courses
  • courses/{id}
Course Section Teachers and students are enrolled into course sections; each section must belong to a parent course.
  • sections
  • sections/{id}

Realm Objects

These objects can be created for different realms.

Resource Description URLs
Enrollment Enrollments are associations between users and groups or course sections.
  • [realm]/enrollments
  • [realm]/enrollments/{id}
  • [realm]/accesscode
  • enrollments

Where [realm] is one of the following:

  • sections/{section_id}
  • groups/{group_id}
Event Events can be created for users, courses, groups, schools, or districts; all events automatically feed into the "upcoming" and "calender" portions of the site.
  • [realm]/events
  • [realm]/events/{id}

Where [realm] is one of the following:

  • districts/{district_id}
  • schools/{school_id}
  • users/{user_id}
  • sections/{section_id}
  • groups/{group_id}
Blog Post Blog posts can be created for all realms.
  • [realm]/posts
  • [realm]/posts/{id}

Where [realm] is one of the following:

  • districts/{district_id}
  • schools/{school_id}
  • users/{user_id}
  • sections/{section_id}
  • groups/{group_id}
Blog Post Comment Comments can be made for any blog post.
  • [realm]/posts/{id}/comments
  • [realm]/posts/{id}/comments/{id}

Where [realm] is one of the following:

  • districts/{district_id}
  • schools/{school_id}
  • users/{user_id}
  • sections/{section_id}
  • groups/{group_id}
Discussion Thread Discussion threads can be created for all realms except users.
  • [realm]/discussions
  • [realm]/discussions/{id}

Where [realm] is one of the following:

  • districts/{district_id}
  • schools/{school_id}
  • sections/{section_id}
  • groups/{group_id}
Discussion Reply Replies are comments made to discussion threads
  • [realm]/discussions/{id}/comments
  • [realm]/discussions/{id}/comments/{id}

Where [realm] is one of the following:

  • districts/{district_id}
  • schools/{school_id}
  • sections/{section_id}
  • groups/{group_id}
Updates Updates are short twitter-style posts found in the Edge for a given realm
  • [realm]/updates
  • [realm]/updates/{id}
  • recent/

Where [realm] is one of the following:

  • users/{user_id}
  • sections/{section_id}
  • groups/{group_id}
Update Comment Update Comments are comments made on updates found in the Edge for a given realm
  • [realm]/updates/{update_id}/comments

Where [realm] is one of the following:

  • users/{user_id}
  • sections/{section_id}
  • groups/{group_id}
Reminders Reminders are user notifications reminding them to complete an action for a given realm
  • /reminders/type
  • [realm]/reminders/type

Where [realm] is one of the following:

  • sections/{section_id}
Media Album Media albums contain audio,video and images with captions and tagging.
  • [realm]/albums
  • [realm]/albums/{album_id}
  • [realm]/albums/{album_id}/content
  • [realm]/albums/{album_id}/content/{album_content_id}

Where [realm] is one of the following:

  • sections/{section_id}
  • groups/{group_id}
Media Album Comments Media Album Comments are comments made on individual content within media albums
  • [realm]/albums/{id}/content/{content_id}/comments

Where [realm] is one of the following:

  • sections/{section_id}
  • groups/{group_id}
Documents Documents are standalone File/Links
  • [realm]/documents
  • [realm]/documents/{id}

Course-Specific Objects

These objects can only be created for the course section realm.

Resource Description URLs
Assignment Assignments are containers for coursework and test/quizzes. Every assignment has an entry in the gradebook.
  • sections/{section_id}/assignments
  • sections/{section_id}/assignments/{id}
Assignment Comments Comments can be made for any assignment.
  • sections/{section_id}/assignments/{id}/comments
  • sections/{section_id}/assignments/{id}/comments/{id}
Grade Grades are associated with an enrollment and an assignment.
  • sections/{section_id}/grades
Grading Scales Grading scales allow you to use non-numeric notations within grades (eg A+, etc)
  • sections/{section_id}/grading_scales
Grading Rubrics Grading rubrics allow you to grade assignments and discussions using a standard of performance for your students.
  • sections/{section_id}/grading_rubrics
  • sections/{section_id}/grading_rubrics/{grading_rubric_id}
Grading Categories Grading categories are required for grading. Assignments without categories will be ungraded.
  • sections/{section_id}/grading_categories
Grading Groups Grading groups are groups of students within a course that can be assigned specific content.
  • sections/{section_id}/grading_groups
Attendance Attendance statuses are associated with an enrollment and a specific date.
  • sections/{section_id}/attendance
  • sections/{section_id}/attendance/{id}
Submissions Formerly "Dropbox"
Submissions are uniquely identified by a Section ID, Grade Item ID, User ID, and Revision ID.
  • sections/{section_id}/submissions/{grade_item_id}
  • sections/{section_id}/submissions/{grade_item_id}/{action}
  • sections/{section_id}/submissions/{grade_item_id}/{user_id}
  • sections/{section_id}/submissions/{grade_item_id}/{user_id}/revisions
  • sections/{section_id}/submissions/{grade_item_id}/{user_id}/revisions/{revision_id}
  • sections/{section_id}/submissions/{grade_item_id}/{user_id}/comments
  • sections/{section_id}/submissions/{grade_item_id}/{user_id}/comments/{comment_id}
Course Folder A course folder request returns all the contents of the folder with pointers to that piece of content if the API supports it. This includes child Folders.
  • courses/{section_id}/folder/{folder_id}
Pages Pages can be used to display any sort of content. HTML can be used to format the content of the page to anything you like.
  • sections/{section_id}/pages
  • sections/{section_id}/pages/{id}
Scorm Package Scorm packages are containers for a Sharable Content Object Reference Model that can be integrated with Schoology.
  • sections/{section_id}/packages
  • sections/{section_id}/packages/{id}
Web Content Package Web Content Packages are website files, compressed in .zip format, that can be added to Schoology course sections.
  • sections/{section_id}/web_packages
  • sections/{section_id}/web_packages/{id}
Completion Each user enrolled in a course section has a completion object with information about the student's progress in the section.
  • sections/{section_id}/completion
  • sections/{section_id}/completion/user/{uid}
External ID Look up a section by its section school code. This is generally used to link Schoology with an external system. For instance, if you have entered a section's section school code to be consistent with a Student Information System (SIS), and you would like to find a section by that section's SIS ID, you can use this API call to do so.
  • sections/ext/{id}

User-Specific Objects

These objects can only be accessed for the users realm.

Resource Description URLs
Friend Request Friend requests can be sent from/received by other Schoology users in your network.
  • users/{user_id}/requests/friends
  • users/{user_id}/requests/friends/{id}
Invite Users can receive requests to join course sections and groups.
  • users/{user_id}/invites/[realm]
  • users/{user_id}/invites/[realm]/{invite_id}

Where [realm] is one of the following:

  • sections
  • groups
Network View a list of users in the given user's network
  • users/{user_id}/network
Grades View a list of the given user's grades
  • users/{id}/grades

User Information

This information can be retrieved for a user object

Resource Description URLs
Sections Course Sections that a user is enrolled in.
  • users/{id}/sections
Groups Groups that a user is enrolled in.
  • users/{id}/groups
Requests Request objects are items that require an action (e.g. a user is requesting to be your friend).
  • users/{id}/requests/{realm}
Invites Invite objects are items that require an action (e.g. a user has invited you to a group)
  • users/{id}/invites/{realm}
External ID Look up a user by their Schoology Unique ID. This is generally used to link Schoology with an external system. For instance, if you have stored the Schoology Unique ID to be consistent with a Student Information System (SIS), and you would like to find a user by their SIS ID, you can use this API call to do so.
  • users/ext/{id}

Other Objects

These objects are not associated with realms.

Resource Description URLs
Grading Period Grading periods (marking periods) determine when a course section is active.
  • gradingperiods
  • gradingperiods/{id}
Role Every user is associated with a collection permissions called roles.
  • roles
  • roles/{id}
Private Messaging Private messages are 'e-mail style' messages that can be sent and shared between multiple users.
  • messages
  • messages/[message folder]
  • messages/[message folder]/{message_id}

Where [message folder] is one of the following:

  • inbox
  • sent
Search Search users, schools, groups and courses.
  • search
Resource Collections Resource Collections are containers for user and group resource templates.
  • collections
  • collections/[collection_id]
Resource Templates Resource templates are objects placed in Resource Collections. Each template has an assigned type (e.g. Document, Assignment, Discussion).
  • collections/[collection_id]/resources
  • [realm]/[realm_id]/resources

Likes and Poll Voting

Likes and Polls are relatively unique actions. They happen on the peripheral of items like updates and comments, but are still essential to understanding the state a relevant object is in. Consequently, the behavior of these actions are modeled in the same vein. Likes are included in objects that can be liked in the GET calls. To actually Like something you make a POST call. Similarly, polls are returned in the attachments array inside of Updates (the only piece of content currently that supports Polls) and to make a vote you make a POST call.

Resource Description URLs
Like Like an object or see a list of users who like a given object
  • like/%id
  • like/%id/comment/%comment_id
Poll Vote on a poll
  • poll/%id/vote

Multi-Calls

Multi-Calls are single POST API calls that allow you to specify multiple API requests in the request body. In effect, you can make several API requests but just one actual REST call, receiving the individual full response body for each API request compiled into a single response body.

Resource Description URLs
Multi-get Make multiple GET calls with a single POST call and receive each response body in full in a single compiled response.
  • multiget
Multi-options Make multiple OPTIONS calls with a single POST call and receive reach response body in full in a single compiled response.
  • multioptions

OPTIONS Calls

API calls made using the OPTIONS method return information about the given object. Read more for details

Profile Images

Profile image sizes can be modified by adding the ‘picture_size’ parameter to any request. For example: https://api.schoology.com/v1/users?picture_size=sm. The following sizes are available:

  • big: width - 250px
  • reg: width - 170px
  • sm: 50x46 px
  • tiny: 35x32 px

CSV Export

We have exposed a GET endpoint to allow bulk exporting of data through our API in csv format. Only school-wide admins have access to this bulk export feature.

  • You can specify field headers you want to include in the csv through a comma separated list in the ‘fields’ query parameter. If no fields are specified, you will receive all fields.
  • Example: csvexport/users?fields=uid,building_nid,name_first,name_last
ResourceAllowed FieldsURLs
Usersuid, school_uid, building_nid, name_title, name_first, name_first_preferred, name_middle, name_last, role_name, name, mail, position, grad_year, birthday, gender, bio, subjects_taught, grades_taught, phone, address, website, interests, activities
  • csvexport/users
Group Enrollmentsuid, school_uid, name_first, name_last, mail, title, group_code, type, status
  • csvexport/group_enrollments