# List the exams open for applications - Endpoint: `GET /v1/{organizationId}/exam` - Production: `https://api.main-team.org/v1/{organizationId}/exam` - Sandbox: `https://apisnd.main-team.org/v1/{organizationId}/exam` - Operation: `listExams` (Exams) - Authentication: `Authorization: Bearer `, a short-lived token you sign with your API key and secret - Permission: `exam/read:$org:$ID` ## Description Lists the organization’s exams that are open for applications, the soonest sitting first. 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 that is not open is not listed, and `getExam` and `createApplication` refuse it too. `session`, `category`, `language`, `grades` and `countries` come back as records rather than ids. An exam with no language is listed, but no student can apply to it. This list is the same for every student: it does not look at grades, countries or what a student already applied for. To see what one of your students can actually apply to, call `listAvailableExams`. A page holds 20 exams unless you ask for up to 100 with `limit`. A read only: nothing changes, and it is safe to repeat. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `organizationId` | path | yes | string | The organization’s `_id`: 24 hexadecimal digits, as `listOrganizations` (`GET /v1/organization`) lists it. | | `page` | query | no | number | Page number. Defaults to 1. | | `limit` | query | no | number | Items per page. Defaults to 20, max 100. | ## Response `200` Success: `message` is "Exams fetched successfully.". ```json { "success": true, "message": "Exams fetched successfully.", "pagination": { "page": 1, "limit": 20, "total": 57, "totalPages": 3 }, "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" } ] } ``` ## Errors | Status | Code | When | | --- | --- | --- | | 401 | [`unauthorized`](https://hub.main-team.org/api/errors#unauthorized) | The token is missing or malformed, is not signed with your account’s `apiSecret`, breaks the `iat` and `exp` rules, has expired or been revoked, or its account is not active. All of these answer the same. | | 403 | [`forbidden`](https://hub.main-team.org/api/errors#forbidden) | The token is valid, but no role on your account allows `exam/read` on the organization in the path, or a role denies it. | | 404 | [`not_found`](https://hub.main-team.org/api/errors#not_found) | `organizationId` is not the `_id` of an organization. | | 429 | [`too_many_requests`](https://hub.main-team.org/api/errors#too_many_requests) | Your account has made more than 100 requests to this operation in the current 60-second window. Wait the seconds in `Retry-After` before sending again. | | 500 | [`internal_error`](https://hub.main-team.org/api/errors#internal_error) | Something failed on our side. Retry later, and quote `request_id` if it goes on. | ## Code samples ### curl ```bash # $TOKEN: a short-lived token you minted with your API key and secret curl -sS 'https://api.main-team.org/v1//exam?page=1&limit=20' \ -H "Authorization: Bearer $TOKEN" ``` ### Node.js ```js const token = process.env.TOKEN; // a short-lived token you minted with your API key and secret const res = await fetch('https://api.main-team.org/v1//exam?page=1&limit=20', { headers: { Authorization: `Bearer ${token}`, }, }); const body = await res.json(); if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`); console.log(body.data, body.pagination); ``` ### PHP ```php /exam?page=1&limit=20'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . $token, ], CURLOPT_RETURNTRANSFER => true, ]); $response = curl_exec($ch); if ($response === false) { throw new RuntimeException(curl_error($ch)); } $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); $body = json_decode($response, true); if ($status >= 400) { $error = $body['error']; throw new RuntimeException("$status {$error['code']}: {$error['message']}"); } print_r($body['data']); print_r($body['pagination']); ```