Version 1.0.0

2026-09-15

Initial release of the v1 partner API, with 35 operations for students, sign-in links, exams, applications, certificates and reports.

Added

Health: getHealth.
API account: getCurrentApiAccount, revokeToken.
Reference data: listCountries, getCountry, listGrades, getGrade, listOrganizations, getOrganization.
Students: listStudents, getStudent, registerStudent, updateStudent, setStudentPassword, listOrgStudents, getOrgStudent, updateOrgStudent, linkStudentSupervisor.
Sign-in links: createSigninLink.
Exams: listExamCategories, getExamCategory, listExams, listAvailableExams, getExam.
Applications: listApplications, listExamApplications, listStudentApplications, getApplication, createApplication, moveApplication, deleteApplication.
Documents: listStudentCertificates, downloadCertificate, listStudentReports, downloadReport.
Authentication with self-signed HS256 tokens, where kid and sub are the apiKey, and iat and exp are required with a lifetime of at most 3600 seconds and 30 seconds of clock tolerance. Every authentication failure answers the same 401 unauthorized.
Permissions by role, checked against the organization each request acts on. An operation with no permission granted answers 403 forbidden.
Response envelopes: { success, message, data, pagination? } on success, and { error: { code, message, documentation_url, request_id } } on failure, with an X-Request-Id header on every response. documentation_url is the code's entry on the partner documentation, https://hub.main-team.org/api/errors#<code>.
Pagination with page (default 1) and limit (default 20, at most 100).
A rate limit of 100 requests per 60 seconds for each account and each operation, with Retry-After and X-RateLimit-* headers. Each operation has its own budget. Going over answers 429 too_many_requests with the message "Too many requests to this operation. Wait the number of seconds in Retry-After, then try again."
createSigninLink: sign-in links that are valid for 120 seconds and work once, for a student with access to that organization.
getStudent, getOrgStudent, getCountry, getGrade, getOrganization and getExamCategory answer 404 not_found for an id they cannot show, as every single read does. A student of another account answers like a missing one.
getApplication, moveApplication and deleteApplication answer 404 with "Application not found!" alike for a missing application and one of another account's student.
listOrganizations and getOrganization serve the five organizations that run exams: stem, hilingua, neo, gmath and coding. On every operation with organizationId in its path, the id of any other organization, mto's included, answers 404 not_found with "Organization not found!", as an id that names no organization does.
getCurrentApiAccount returns the account's roles, each with effect, action, target and, when set, authorized, to compare with an operation's x-permission.
registerStudent requires firstName, lastName, email, birth, sex, country, grade, city and school, with birth a date that exists, as DD/MM/YYYY, and names a missing field in its 400 ("lastName should not be empty"). updateStudent and updateOrgStudent hold the fields they are sent to the same rules, and refuse null for firstName, lastName, birth, sex and phone. registerStudent refuses a null phone too.
activatedPlatformsThisSeason on registerStudent, updateStudent and updateOrgStudent takes common, stem, hilingua, neo, gmath and coding. The two updates add to the student's list and never remove from it. updateOrgStudent without the field, even with an empty body, adds its own organization, unless the list already holds common. All three refuse null for it with 400; registerStudent without it stores ["common"].
Passwords: a password at registerStudent, and setStudentPassword, need auth/signin on mto. A password is 5 characters to 72 bytes and contains none of the student's own details. setStudentPassword answers 409 once the student has confirmed their email address.
linkStudentSupervisor answers every refusal with the same 404 "Not found!".
createApplication is safe to repeat: the same student and exam answer 200 with the existing application.

Release notes

The first release of the Main Team API. Every path is under https://api.main-team.org/v1. Nothing here replaces an earlier version: each behavior below is how the API works from day one, listed so you can see the rules your integration will meet in one place. Each item links to the page that explains it.

Operations

35 operations in eight groups:

Group	Operations
Health	getHealth
API account	getCurrentApiAccount, revokeToken
Reference data	listCountries, getCountry, listGrades, getGrade, listOrganizations, getOrganization
Students	listStudents, getStudent, registerStudent, updateStudent, setStudentPassword, listOrgStudents, getOrgStudent, updateOrgStudent, linkStudentSupervisor
Sign-in links	createSigninLink
Exams	listExamCategories, getExamCategory, listExams, listAvailableExams, getExam
Applications	listApplications, listExamApplications, listStudentApplications, getApplication, createApplication, moveApplication, deleteApplication
Documents	listStudentCertificates, downloadCertificate, listStudentReports, downloadReport

Notable behaviors

Authentication and access

You sign your own tokens: HS256 with your apiSecret, kid and sub set to your apiKey, iat and exp required, at most 3600 seconds apart, with 30 seconds of clock tolerance. Every authentication failure answers the same 401 unauthorized. See Authentication.
revokeToken ends one token early. Role changes and deactivation of your account take effect within 60 seconds.
Every operation except the health check needs a permission from your roles, checked against the organization the request acts on; operations without an organization in their path act on mto. Setting a password needs auth/signin on mto. See Permissions.
{organizationId} in a path is the organization's _id from listOrganizations, never its slug. An unknown id answers 404 with Organization not found!, after the token is checked. See Organizations.
listOrganizations lists the five organizations that run exams: stem, hilingua, neo, gmath and coding. mto, the core record, is not listed: the operations without an organization in their path act on it.
Your account sees only the students it registered and the records reached through them. Another account's record answers like a missing one.

Requests and responses

JSON bodies in UTF-8, at most 100 kB (413 above that). A field the operation does not accept is refused with 400 naming it. See Requests and responses.
Success responses use { success, message, data, pagination? }; errors use { error: { code, message, documentation_url, request_id } }, where documentation_url is the code's entry on the errors page, https://hub.main-team.org/api/errors#<code>. getCurrentApiAccount returns the account without the envelope, and the downloads return the file itself.
Every single read answers 404 not_found for a record it cannot show, including getStudent, getOrgStudent, getCountry, getGrade, getOrganization and getExamCategory.
Every response carries X-Request-Id. Quote it when you contact support.
Lists take page (default 1) and limit (default 20, at most 100; larger values are clamped). See Pagination.
Two catalog codes, invalid_email and unprocessable_entity, are reserved: no operation returns them in 1.0.0. See Errors.

Rate limits

100 requests per 60 seconds per account and per operation, whichever organization is in the path. Each operation is counted on its own. See Rate limits.
Going over answers 429 with Retry-After and the message "Too many requests to this operation. Wait the number of seconds in Retry-After, then try again.", and blocks that operation for 60 seconds. Counted responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

Students

Registration is not idempotent. An email address already registered to your account answers 409 with that student's id; one held by anyone else answers 409 without an id. See Students.
Every student gets a username at registration, which the API never changes.
Registration requires firstName, lastName, email, birth, sex, country, grade, city and school, and birth must be a date that exists, as DD/MM/YYYY. Both updates hold the fields you send to the same rules, and refuse null for a field a student can't be without.
A student can use every organization by default (activatedPlatformsThisSeason: ["common"]). The list takes common and the slugs stem, hilingua, neo, gmath and coding. Updates only add to it and never remove anything. Updating a student through an organization without the field, even with an empty body, gives the student access to that organization.
Changing a student's email address withdraws its confirmation until the student confirms the new address.
Passwords are at least 5 characters and at most 72 bytes, may not contain the student's name, username or email address, and can no longer be set once the student has confirmed their email address (409). See Passwords.

A sign-in link works once and for 120 seconds. Its optional redirect must be a path on the organization's site that starts with a single /. See Sign-in links.
A student without access to the organization gets 403. An unconfirmed email address does not block a link; the panel asks the student to confirm it and lets them choose to do it later.
An organization creates its own copy of a student at their first sign-in there. Until then, applications, the student's application, certificate and report lists on that organization answer 409, and a supervisor link answers 404.

Exams and applications

Only open exams are listed or can be read by id. The exam picker, listAvailableExams, offers one student exactly what they may apply for. See Exams.
Creating the same application again answers 200 with Application already exists. and the existing application. See Applications.
A move is refused once the exam has started, and checked against the same rules as a new application. A paid application moves only to an exam with the same price. An AI Challenge application cannot be moved once the student has used part of their image quota.
An application with a settled payment cannot be deleted (409). The API records payments but never charges or refunds anyone.
getApplication, moveApplication and deleteApplication answer 404 with Application not found! alike for an application that does not exist and one of another account's student.

Certificates and reports

Only released documents are listed or downloaded. A download by _id or shortId answers one 404 for a document that is missing, not released, not yours or has no file. See Certificates and reports.