Reference
API reference
Every endpoint, grouped by what it works on. Each path starts with /v1 on https://api.main-team.org, and an endpoint that names a permission takes a bearer token.
Health
1 endpointWhether the API is up. No token needed, so it is the first call to make against an environment.
API account
2 endpointsThe account your token belongs to, and revoking a token before it expires.
Reference data
6 endpointsCountries, grades and organizations. A student’s country and grade take these _ids, and so does every :organizationId in a path.
- GETList the countries a student can be registered in
/v1/ country - GETFetch one country by its id
/v1/ country/ {id} - GETList the grades a student can be registered with
/v1/ grade - GETFetch one grade by its id
/v1/ grade/ {id} - GETList the organizations and their ids
/v1/ organization - GETFetch one organization by its id
/v1/ organization/ {id}
Students
12 endpointsRegistering your students, reading and updating them, setting a password, and what each organization holds for them. You only ever see the students your account registered.
- GETList your students
/v1/ student - POSTRegister a student
/v1/ student - POSTCheck a registration without registering the student
/v1/ student/ check - POSTRegister many students at once
/v1/ student/ import - GETFollow a batch of students you sent
/v1/ student/ import/ {importId} - GETFetch one of your students
/v1/ student/ {studentId} - PUTUpdate one of your students
/v1/ student/ {studentId} - PUTSet the sign-in password of one of your students
/v1/ student/ {studentId}/ password - GETList your students who can use this organization
/v1/ {organizationId}/ student - GETFetch one of your students, if they can use this organization
/v1/ {organizationId}/ student/ {studentId} - PUTUpdate one of your students and give them access to this organization
/v1/ {organizationId}/ student/ {studentId} - PUTLink one of your students to a supervisor on this organization
/v1/ {organizationId}/ student/ {studentId}/ supervisor
Sign-in links
1 endpointLinks that sign one of your students into an organization’s panel. Each works once and expires two minutes after it is issued.
Exams
5 endpointsThe exam categories and exams an organization runs, and the ones one of your students can apply to.
- GETList the exams open for applications
/v1/ {organizationId}/ exam - GETList an organization’s exam categories
/v1/ {organizationId}/ exam-category - GETFetch one exam category
/v1/ {organizationId}/ exam-category/ {categoryId} - GETList the exams one of your students can apply to
/v1/ {organizationId}/ exam/ available/ {studentId} - GETFetch one exam that is open for applications
/v1/ {organizationId}/ exam/ {examId}
Applications
7 endpointsEntering your students for exams: creating, reading, moving and deleting their applications.
- GETList your students’ applications in this organization
/v1/ {organizationId}/ application - POSTEnter one of your students for an exam
/v1/ {organizationId}/ application - GETList your students’ applications for one exam
/v1/ {organizationId}/ application/ exam-applications/ {examId} - GETList one of your students’ applications in this organization
/v1/ {organizationId}/ application/ student-applications/ {studentId} - GETFetch one of your students’ applications
/v1/ {organizationId}/ application/ {applicationId} - PUTMove one of your students’ applications to another exam
/v1/ {organizationId}/ application/ {applicationId} - DELETEWithdraw one of your students from an exam
/v1/ {organizationId}/ application/ {applicationId}
Documents
4 endpointsYour students’ certificates and reports: listing them and downloading the files.
- GETDownload a certificate file
/v1/ {organizationId}/ certificate/ download/ {certificateId} - GETList one of your students’ released certificates
/v1/ {organizationId}/ certificate/ {userId} - GETDownload a result report file
/v1/ {organizationId}/ report/ download/ {reportId} - GETList one of your students’ released result reports
/v1/ {organizationId}/ report/ {userId}
Group challenges
9 endpointsOnline group challenges your students take part in: the challenges, which of your students can join, the groups they are in, each step and its files, what happened in a group, and submitting on your student’s behalf.
Read the Group challenges guide
- GETList the group challenges an organization runs
/v1/ {organizationId}/ group-challenge - GETFetch one group challenge
/v1/ {organizationId}/ group-challenge/ {challengeId} - GETList the groups your students are in for a group challenge
/v1/ {organizationId}/ group-challenge/ {challengeId}/ group - GETFetch one group, with its steps and files
/v1/ {organizationId}/ group-challenge/ {challengeId}/ group/ {groupId} - GETList what has happened in one group
/v1/ {organizationId}/ group-challenge/ {challengeId}/ group/ {groupId}/ activity - POSTSend a group’s finished work for one of your students
/v1/ {organizationId}/ group-challenge/ {challengeId}/ group/ {groupId}/ final-submit - POSTSubmit one step of a group for one of your students
/v1/ {organizationId}/ group-challenge/ {challengeId}/ group/ {groupId}/ step/ {stepId}/ submit - GETList your students’ eligibility and groups for a group challenge
/v1/ {organizationId}/ group-challenge/ {challengeId}/ student - GETFetch one of your students’ eligibility and group for a group challenge
/v1/ {organizationId}/ group-challenge/ {challengeId}/ student/ {studentId}
Permissions
Each endpoint needs one permission, granted by a role on your API account. A role allows an action on a target:
- Action
- The permission itself, such as
student/read.student/*covers everystudent/…action, and*covers all of them. - Core record
- An endpoint with no organization in its path. A role counts when its target is
mtoor*. - Per organization
- An endpoint under
/v1/{organizationId}. A role counts when its target is that organization's slug, or*.
| Endpoint | Permission | Target |
|---|---|---|
| Health | ||
Check that the API is upGET/ | none | No token |
| API account | ||
Revoke the token you send, before it expiresPOST/ | api/* | Core record |
Fetch the API account your token belongs toGET/ | api/* | Core record |
| Reference data | ||
List the countries a student can be registered inGET/ | country/read | Core record |
Fetch one country by its idGET/ | country/read | Core record |
List the grades a student can be registered withGET/ | grade/read | Core record |
Fetch one grade by its idGET/ | grade/read | Core record |
List the organizations and their idsGET/ | organization/read | Core record |
Fetch one organization by its idGET/ | organization/read | Core record |
| Students | ||
List your studentsGET/ | student/read | Core record |
Register a studentPOST/ | student/create | Core record |
Check a registration without registering the studentPOST/ | student/create | Core record |
Register many students at oncePOST/ | student/create | Core record |
Follow a batch of students you sentGET/ | student/create | Core record |
Fetch one of your studentsGET/ | student/read | Core record |
Update one of your studentsPUT/ | student/update | Core record |
Set the sign-in password of one of your studentsPUT/ | auth/signin | Core record |
List your students who can use this organizationGET/ | student/read | Per organization |
Fetch one of your students, if they can use this organizationGET/ | student/read | Per organization |
Update one of your students and give them access to this organizationPUT/ | student/update | Per organization |
Link one of your students to a supervisor on this organizationPUT/ | student/update | Per organization |
| Sign-in links | ||
Create a single-use sign-in link for one of your studentsPOST/ | auth/signin | Per organization |
| Exams | ||
List the exams open for applicationsGET/ | exam/read | Per organization |
List an organization’s exam categoriesGET/ | exam-category/read | Per organization |
Fetch one exam categoryGET/ | exam-category/read | Per organization |
List the exams one of your students can apply toGET/ | exam/read | Per organization |
Fetch one exam that is open for applicationsGET/ | exam/read | Per organization |
| Applications | ||
List your students’ applications in this organizationGET/ | application/read | Per organization |
Enter one of your students for an examPOST/ | application/create | Per organization |
List your students’ applications for one examGET/ | application/read | Per organization |
List one of your students’ applications in this organizationGET/ | application/read | Per organization |
Fetch one of your students’ applicationsGET/ | application/read | Per organization |
Move one of your students’ applications to another examPUT/ | application/update | Per organization |
Withdraw one of your students from an examDELETE/ | application/delete | Per organization |
| Documents | ||
Download a certificate fileGET/ | certificate/read | Per organization |
List one of your students’ released certificatesGET/ | certificate/read | Per organization |
Download a result report fileGET/ | report/read | Per organization |
List one of your students’ released result reportsGET/ | report/read | Per organization |
| Group challenges | ||
List the group challenges an organization runsGET/ | group-challenge/read | Per organization |
Fetch one group challengeGET/ | group-challenge/read | Per organization |
List the groups your students are in for a group challengeGET/ | group-challenge/read | Per organization |
Fetch one group, with its steps and filesGET/ | group-challenge/read | Per organization |
List what has happened in one groupGET/ | group-challenge/read | Per organization |
Send a group’s finished work for one of your studentsPOST/ | group-challenge/submit | Per organization |
Submit one step of a group for one of your studentsPOST/ | group-challenge/submit | Per organization |
List your students’ eligibility and groups for a group challengeGET/ | group-challenge/read | Per organization |
Fetch one of your students’ eligibility and group for a group challengeGET/ | group-challenge/read | Per organization |