Skip to content
Olympiads Hub
API documentation
View as MarkdownOpen in Claude

Exams

List the exams one of your students can apply to

GET
/v1/{organizationId}/exam/available/{studentId}
Try it in the sandbox

The exams one of your students can apply to in this organization, as a tree: categories, each holding its sittings, each holding the languages it can be sat in. Every leaf carries matchedExam, and matchedExam._id is the examId that createApplication takes.

Only your students. A student is yours when your account registered it. Another account’s student answers 404, exactly like an id that is nobody’s.

What is offered. An exam is in the tree when all of these hold:

  • it is open for applications, as listExams lists it. An exam is open for applications while all three hold: it is not closed to applications (preventApplication is not true), its sitting (session.date) is still to come, and its category is active. It stops being open at the moment its sitting starts.
  • the student’s grade is one of the exam’s grades;
  • the exam is open to the student’s country, or to every country. When the student has no country, or the organization does not list it, only exams open to every country are offered;
  • the exam has a language;
  • the student holds no application in this organization for the same category on the same sitting.

createApplication refuses an exam by the same rules, so what is listed here is what it accepts, as long as nothing changes in between. It also needs the student to have signed in to the organization once (createSigninLink); this list does not.

Order and size. Categories in the organization’s order, sittings soonest first, languages in order. Not paginated: data is the whole tree, and [] when nothing is offered. No branch is ever empty.

Call first: registerStudent, or listStudents, for the studentId. The student needs a grade: one without is refused with 400 until you set it with updateStudent or updateOrgStudent. A read only: nothing changes, and it is safe to repeat.

Parameters

Path parameters

NameTypeDescription
organizationIdrequiredstringpattern ^[0-9a-f]{24}$

The organization’s _id: 24 hexadecimal digits, as listOrganizations (GET /v1/organization) lists it.

Example 64b7f0c2a1d3e4f5a6b7c8d9

studentIdrequiredstring

The _id of one of your students, as registerStudent answered and listStudents lists it.

Responses

200 OK

Success: message is "Available exams fetched successfully.".

Body

  • successbooleanrequired

    Always true on a success.

    one oftrue

  • messagestringrequired

    exampleAvailable exams fetched successfully.

  • dataarray of AvailableExamCategoryResponserequired

    10 fields of each item

    • _idstringrequired

      The category’s id.

      example6650a1b2c3d4e5f6a7b8c9e3

    • namestring

      The category’s name, as students see it.

      exampleMathematics

    • altNamestring

      A second name for the category, where one is set.

      exampleMaths

    • ordernumber

      Where the category sorts among the others, lowest first. The available-exams tree is in this order.

      example1

    • isActiveboolean

      Whether the category is live. No exam in an inactive category is open for applications.

      exampletrue

    • nonAcceptedReplacementsarray of string

      Ids of the categories an application in this one may not be moved to: moveApplication refuses such a move.

      example["6650a1b2c3d4e5f6a7b8c9ea"]

    • studyMaterialLinksarray of string

      Links to study material for the category.

      example["https://example.org/study/mathematics"]

    • createdAtstring

      When the record was created.

      formatdate-timeexample2026-09-01T09:30:00.000Z

    • updatedAtstring

      When the record last changed.

      formatdate-timeexample2026-09-02T14:05:00.000Z

    • sessionsarray of AvailableExamSessionResponserequired

      The sittings in this category the student can apply to, soonest first. Never empty. A sitting the student already holds an application for in this category is left out.

      14 fields of each item

      • _idstringrequired

        The sitting’s id.

        example6650a1b2c3d4e5f6a7b8c9e2

      • sessionNamestring

        The sitting’s name.

        exampleNovember 2026

      • datestring

        When the sitting takes place. Its exams are open for applications until this moment, and not after.

        formatdate-timeexample2026-11-14T10:00:00.000Z

      • startTimestring

        The start time as the organization wrote it. For the moment itself, read date.

        example10:00

      • tzstring

        global: the sitting starts at one moment everywhere. local: it starts at the same clock time in each student’s own time zone, their country’s tz.

        one ofgloballocal

        exampleglobal

      • sessionAliasstring

        A second name for the sitting, shown to students.

        exampleAutumn round

      • sessionNotestring

        A note about the sitting, shown to students.

        examplePlease join ten minutes early.

      • enableSimulationboolean

        Whether students get a practice run before the sitting.

        exampletrue

      • simulationDatestring

        When the practice run opens.

        formatdate-timeexample2026-11-07T10:00:00.000Z

      • simulationEndDatestring

        When the practice run closes.

        formatdate-timeexample2026-11-08T10:00:00.000Z

      • relatedSessionstring

        Set on a make-up sitting: the id of the sitting it belongs to. An application to an exam on a make-up sitting is removed 6 hours after it is made.

        example6650a1b2c3d4e5f6a7b8c9e2

      • createdAtstring

        When the record was created.

        formatdate-timeexample2026-09-01T09:30:00.000Z

      • updatedAtstring

        When the record last changed.

        formatdate-timeexample2026-09-02T14:05:00.000Z

      • languagesarray of AvailableExamLanguageResponserequired

        The languages the student can take this sitting in, in the organization’s order. Never empty.

        7 fields of each item

        • _idstringrequired

          The language’s id.

          example6650a1b2c3d4e5f6a7b8c9e4

        • namestring

          The language’s name.

          exampleEnglish

        • codestring

          A short language code.

          exampleen

        • ordernumber

          Where the language sorts among the others, lowest first. The available-exams tree is in this order.

          example1

        • createdAtstring

          When the record was created.

          formatdate-timeexample2026-09-01T09:30:00.000Z

        • updatedAtstring

          When the record last changed.

          formatdate-timeexample2026-09-02T14:05:00.000Z

        • matchedExamobject · ExamRecordResponserequired

          The one exam this category, sitting and language make up. Its _id is the examId that createApplication takes; its session, category and language are the ids of the levels above.

          14 fields of matchedExam

          • _idstringrequired

            The exam’s id: the examId that createApplication and moveApplication take.

            example6650a1b2c3d4e5f6a7b8c9e1

          • sessionstring

            The id of the sitting the exam is on.

            example6650a1b2c3d4e5f6a7b8c9e2

          • categorystring

            The id of the exam’s category.

            example6650a1b2c3d4e5f6a7b8c9e3

          • languagestring

            The id of the language the exam is sat in, when it has one.

            example6650a1b2c3d4e5f6a7b8c9e4

          • gradesarray of string

            The grades that may sit the exam. A student in any other grade is not offered it and cannot apply to it. Grade ids are the same in every organization.

            example["6650a1b2c3d4e5f6a7b8c9d4"]

          • countriesarray of string

            The countries the exam is restricted to; empty or absent, it is open to every country. Ids of the organization’s own country records, which need not match the ones listCountries gives.

            example[]

          • examTypestring

            standard or essay.

            one ofstandardessay

            examplestandard

          • examTimenumber

            The time limit, in minutes, from when the student starts.

            example75

          • durationnumber

            How many hours the exam can be started in, counted from the start of the sitting.

            example15

          • questionCountnumber

            How many questions the exam has.

            example30

          • pricenumber

            What an application costs, as a number; no currency is given. Absent when the exam has no price: an application to it is charged 0.

            example25

          • preventApplicationboolean

            Whether the exam is closed to new applications. A closed exam is never listed, so on the exam reads this is false or absent.

            examplefalse

          • createdAtstring

            When the record was created.

            formatdate-timeexample2026-09-01T09:30:00.000Z

          • updatedAtstring

            When the record last changed.

            formatdate-timeexample2026-09-02T14:05:00.000Z

Headers

X-RateLimit-Limit integer

Requests your account may make to this operation per window (100).

X-RateLimit-Remaining integer

Requests left in the current window.

X-RateLimit-Reset integer

Seconds until the current window ends.

Example

{
  "success": true,
  "message": "Available exams fetched successfully.",
  "data": [
    {
      "_id": "6650a1b2c3d4e5f6a7b8c9e3",
      "name": "Mathematics",
      "altName": "Maths",
      "order": 1,
      "isActive": true,
      "nonAcceptedReplacements": [
        "6650a1b2c3d4e5f6a7b8c9ea"
      ],
      "studyMaterialLinks": [
        "https://example.org/study/mathematics"
      ],
      "createdAt": "2026-09-01T09:30:00.000Z",
      "updatedAt": "2026-09-02T14:05:00.000Z",
      "sessions": [
        {
          "_id": "6650a1b2c3d4e5f6a7b8c9e2",
          "sessionName": "November 2026",
          "date": "2026-11-14T10:00:00.000Z",
          "startTime": "10:00",
          "tz": "global",
          "sessionAlias": "Autumn round",
          "sessionNote": "Please join ten minutes early.",
          "enableSimulation": true,
          "simulationDate": "2026-11-07T10:00:00.000Z",
          "simulationEndDate": "2026-11-08T10:00:00.000Z",
          "relatedSession": "6650a1b2c3d4e5f6a7b8c9e2",
          "createdAt": "2026-09-01T09:30:00.000Z",
          "updatedAt": "2026-09-02T14:05:00.000Z",
          "languages": [
            {
              "_id": "6650a1b2c3d4e5f6a7b8c9e4",
              "name": "English",
              "code": "en",
              "order": 1,
              "createdAt": "2026-09-01T09:30:00.000Z",
              "updatedAt": "2026-09-02T14:05:00.000Z",
              "matchedExam": {
                "_id": "6650a1b2c3d4e5f6a7b8c9e1",
                "session": "6650a1b2c3d4e5f6a7b8c9e2",
                "category": "6650a1b2c3d4e5f6a7b8c9e3",
                "language": "6650a1b2c3d4e5f6a7b8c9e4",
                "grades": [
                  "6650a1b2c3d4e5f6a7b8c9d4"
                ],
                "countries": [],
                "examType": "standard",
                "examTime": 75,
                "duration": 15,
                "questionCount": 30,
                "price": 25,
                "preventApplication": false,
                "createdAt": "2026-09-01T09:30:00.000Z",
                "updatedAt": "2026-09-02T14:05:00.000Z"
              }
            }
          ]
        }
      ]
    }
  ]
}

Example request

# $TOKEN: a short-lived token you minted with your API key and secret
curl -sS 'https://api.main-team.org/v1/<organizationId>/exam/available/<studentId>' \
  -H "Authorization: Bearer $TOKEN"

Search the API documentation

Guides, endpoints by name, path or permission, and error codes such as not_found.