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

Exams

Fetch one exam that is open for applications

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

Returns one exam, in the shape listExams lists it, provided it is open for applications. 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.

An exam listExams would not list cannot be read here either: an exam that exists but is not open answers 404, with a message that tells it apart from an id that names no exam. Like the list, this says nothing about whether a given student may apply; listAvailableExams does.

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

examIdrequiredstring

The exam’s _id, as listExams lists it or as matchedExam._id on a leaf of listAvailableExams carries it.

Responses

200 OK

Success: message is "Exam fetched successfully.".

Body

  • successbooleanrequired

    Always true on a success.

    one oftrue

  • messagestringrequired

    exampleExam fetched successfully.

  • dataobject · ExamResponserequired

    An exam that is open for applications, with its sitting, category, language, grades and countries resolved into records.

    14 fields of data

    • _idstringrequired

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

      example6650a1b2c3d4e5f6a7b8c9e1

    • sessionobject · ExamSessionResponserequired

      The sitting the exam is on.

      13 fields of session

      • _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

    • categoryobject · ExamCategoryResponserequired

      The exam’s category.

      9 fields of category

      • _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

    • languageobject · LanguageResponsenullable

      The language the exam is sat in. Absent or null when it has none: such an exam is listed, but not offered to students, and cannot be applied to.

      6 fields of language

      • _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

    • gradesarray of GradeResponserequired

      The grades that may sit the exam. A student in any other grade is not offered it and cannot apply to it.

      4 fields of each item

      • _idstringrequired

        The grade’s id: what grade takes when you register or update a student. A grade has the same id in every organization.

        example6650a1b2c3d4e5f6a7b8c9d4

      • namestring

        The grade, as a number in a string, 1 to 12. grade accepts this name as well as the id.

        example10

      • createdAtstring

        When the record was created. The grade list is in this order.

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

      • updatedAtstring

        When the record last changed.

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

    • countriesarray of CountryResponserequired

      The countries the exam is restricted to; empty or absent, it is open to every country. These are the organization’s own country records, whose ids need not match the ones listCountries gives: compare them with a student’s country by iso2.

      9 fields of each item

      • _idstringrequired

        The country’s id: what country takes when you register or update a student.

        example6650a1b2c3d4e5f6a7b8c9d1

      • namestring

        The country’s name, in capitals.

        exampleUNITED STATES

      • iso3string

        The ISO 3166-1 alpha-3 code, in capitals.

        exampleUSA

      • iso2string

        The ISO 3166-1 alpha-2 code, in capitals. A student’s username starts with it.

        exampleUS

      • tzstring

        The IANA time zone a sitting on local time is read in for students in this country (see tz on a sitting).

        exampleAmerica/New_York

      • dialCodestring

        The international dialling code, with its +.

        example+1

      • flagstring

        The country’s flag, as an emoji.

        example🇺🇸

      • 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

    • 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": "Exam fetched successfully.",
  "data": {
    "_id": "6650a1b2c3d4e5f6a7b8c9e1",
    "session": {
      "_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"
    },
    "category": {
      "_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"
    },
    "language": {
      "_id": "6650a1b2c3d4e5f6a7b8c9e4",
      "name": "English",
      "code": "en",
      "order": 1,
      "createdAt": "2026-09-01T09:30:00.000Z",
      "updatedAt": "2026-09-02T14:05:00.000Z"
    },
    "grades": [
      {
        "_id": "6650a1b2c3d4e5f6a7b8c9d4",
        "name": "10",
        "createdAt": "2026-09-01T09:30:00.000Z",
        "updatedAt": "2026-09-02T14:05:00.000Z"
      }
    ],
    "countries": [
      {
        "_id": "6650a1b2c3d4e5f6a7b8c9d1",
        "name": "UNITED STATES",
        "iso3": "USA",
        "iso2": "US",
        "tz": "America/New_York",
        "dialCode": "+1",
        "flag": "🇺🇸",
        "createdAt": "2026-09-01T09:30:00.000Z",
        "updatedAt": "2026-09-02T14:05:00.000Z"
      }
    ],
    "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/<examId>' \
  -H "Authorization: Bearer $TOKEN"

Search the API documentation

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