{"openapi":"3.0.1","info":{"title":"Evalmee Public API V2","version":"v2","description":"Welcome to the Evalmee Public API documentation. This API allows you to interact with our platform programmatically.\n\n## Authentication\n\nThe API uses the OAuth 2.0 **Client Credentials Flow**.\nClient credentials grant access to all resources of your organisation.\n\nTo authenticate:\n1. Obtain your client credentials: `client_id` and `client_secret`\n2. Request an access token from `/api/public/auth/token` with body:\n  ```json\n  {\n    \"client_id\": \"YOUR_CLIENT_ID\",\n    \"client_secret\": \"YOUR_CLIENT_SECRET\",\n    \"grant_type\": \"client_credentials\"\n  }\n  ```\n3. Include the access token in every request using Bearer authentication scheme with the header `Authorization: Bearer <access_token>`.\n\nTokens are valid for **24 hours**.\n\nThe API is **HTTPS-only**; HTTP requests are redirected to HTTPS.\n\n## Common Conventions\n\n- Responses are returned in **JSON** format.\n- Requests that include a JSON body (POST / PATCH) must set `Content-Type: application/json`.\n- All **timestamps** use the ISO 8601 standard (`2025-04-30T16:15:00Z`).\n- Pagination uses `page` and `per_page` query parameters; metadata comes in `\"meta\"` & `\"links\"`.\n- Responses include HATEOAS links for easy navigation.\n- This spec covers **/v2/**. Breaking changes will appear under **/v3/**.\n\n## Errors\n\nErrors carry a machine slug in `\"error\"` and the human explanation in\n`\"messages\"`. Branch on the slug, never on the message text. Some\nrefusals add a `\"meta\"` object; the key is omitted entirely when empty.\n\n```json\n{ \"error\": \"invalid_schema\", \"status_code\": 422, \"messages\": [\"name is missing\"] }\n```\n\n### Account state (403)\n\nWrite endpoints are refused when your organization's account is\nread-only (trial ended, or subscription cancelled), or when a renewal\npayment failed and its grace window elapsed:\n\n| `error` | Meaning | Affected writes |\n|---|---|---|\n| `billing_read_only` | trial expired, or subscription cancelled | everything that creates: exams, subjects, assessment criteria, examinees, exam sessions |\n| `billing_past_due` | payment failed, grace window elapsed | launching and scheduling only |\n\n`meta` describes the refusal (`action`, `state`, `message`, `upsell`),\nso a client can show the reason and what to do about it.\n\n**Reads, exports and deletes are never refused for account state** —\ndata is never held hostage. A `403` with an empty body means something\nelse entirely: your API key has no access to that record.\n"},"tags":[{"name":"Exams","description":"An exam represents a collection of questions assigned to examinees. \n\nIt can have one or more exam sessions. \n\nAn examinee can take an exam in one or more exam sessions.\n"},{"name":"Exam Sessions","description":"An exam session represents a time period during which examinees can take a given exam, with options for group restrictions and self-enrollment. \n\n\nAn exam session can either:\n- be restricted to one or more groups of examinees\n- have no restriction: all the examinees can take the exam in this session\n"},{"name":"Examinees","description":"An examinee represents a person enrolled in a given exam, including their identity and group membership.\n\n"},{"name":"Assessment Criteria","description":"An assessment criterion defines an evaluation dimension for an exam. Each question is graded against all criteria with configurable points, yielding per-criterion grades. Criteria typically map to competencies from external frameworks (e.g. RNCP in France) but can be custom-defined.\n"},{"name":"Exam Attempts","description":"An exam attempt represents a participation of an examinee in a given exam session.\n\nIf an examinee is assigned to one or more exam sessions of the same exam, they will have one exam attempt per session.\n\nThe exam attempt is created when the examinee is invited by mail to the exam session or when they access the exam for the first time.\n"},{"name":"Exam Results","description":"An exam result represents the overall performance of an examinee in a given exam.\n\nA result is computed from one or more exam attempts and includes the final grade.\n"}],"paths":{"/exams/{exam_id}/assessment_criteria":{"parameters":[{"name":"exam_id","in":"path","required":true,"example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","description":"The id of the exam in Evalmee","schema":{"type":"string"}}],"get":{"summary":"List all assessment criteria","tags":["Assessment Criteria"],"description":"List all assessment criteria for a given exam.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/assessment_criterion"}},"meta":{"$ref":"#/components/schemas/pagination_meta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"unauthorized","status_code":401}}},"schema":{"$ref":"#/components/schemas/error"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}}}},"post":{"summary":"Create an assessment criterion","tags":["Assessment Criteria"],"description":"Create a new assessment criterion for a given exam.\n","parameters":[],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/assessment_criterion"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"unauthorized","status_code":401}}},"schema":{"$ref":"#/components/schemas/error"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"examples":{"invalid_schema":{"value":{"error":"invalid_schema","status_code":422,"messages":["name must be filled"]}}},"schema":{"$ref":"#/components/schemas/error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The name of the assessment criterion","example":"Data collection methodology","type":"string","minLength":1},"description":{"description":"Description of the criterion","example":"Use of appropriate tools and methods to gather information in a structured manner","type":"string","nullable":true},"code":{"description":"Short code (max 10 chars, auto-generated if omitted)","example":"CE1.1","type":"string","minLength":1,"maxLength":10}},"required":["name"]},"examples":{"Basic":{"summary":"Basic assessment criterion","value":{"name":"Data collection methodology"}},"With details":{"summary":"Assessment criterion with details","value":{"name":"Data collection methodology","description":"Use of appropriate tools and methods to gather information in a structured manner","code":"CE1.1"}}}}}}}},"/exams/{exam_id}/assessment_criteria/{id}":{"parameters":[{"name":"exam_id","in":"path","required":true,"example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","description":"The id of the exam in Evalmee","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","description":"The id of the assessment criterion in Evalmee","schema":{"type":"string"}}],"get":{"summary":"Retrieve an assessment criterion","tags":["Assessment Criteria"],"description":"Retrieve a given assessment criterion, including its name, code and description.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/assessment_criterion"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}}}},"patch":{"summary":"Update an assessment criterion","tags":["Assessment Criteria"],"description":"Update the properties of a given assessment criterion.\nCannot update a criterion linked to questions with frozen grading criteria.\n","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/assessment_criterion"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"description":"Unprocessable Entity - frozen criteria","content":{"application/json":{"examples":{"frozen_criteria":{"value":{"error":"frozen_criteria","status_code":422,"messages":["Cannot update a criterion linked to questions with frozen grading criteria"]}}},"schema":{"$ref":"#/components/schemas/error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The name of the assessment criterion","example":"Data collection methodology","type":"string","minLength":1},"description":{"description":"Description of the criterion","example":"Use of appropriate tools and methods to gather information in a structured manner","type":"string","nullable":true},"code":{"description":"Short code (max 10 chars, auto-generated if omitted)","example":"CE1.1","type":"string","minLength":1,"maxLength":10}}},"examples":{"Basic":{"summary":"Basic assessment criterion","value":{"name":"Data collection methodology"}}}}}}},"delete":{"summary":"Delete an assessment criterion","tags":["Assessment Criteria"],"description":"Delete a given assessment criterion.\nCannot delete a criterion linked to questions with frozen grading criteria.\n","responses":{"204":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"unauthorized","status_code":401}}}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}}}}},"422":{"description":"Unprocessable Entity - frozen criteria","content":{"application/json":{"examples":{"frozen_criteria":{"value":{"error":"frozen_criteria","status_code":422,"messages":["Cannot modify a criterion linked to questions with frozen grading criteria"]}}}}}}}}},"/emails":{"get":{"summary":"List the emails sent to examinees","tags":["Emails"],"description":"List the emails sent to the examinees of your school, most recent first.\n\nEvery email type is listed, including the ones no endpoint can trigger. Combine the\nfilters to answer \"what was sent for this session\" or \"what was sent to this examinee\".\n","parameters":[{"name":"exam_id","in":"query","required":false,"example":"a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6","description":"Only return emails sent about this exam","schema":{"type":"string"}},{"name":"exam_session_id","in":"query","required":false,"example":"a1B2c3d4e5","description":"Only return emails sent about this exam session","schema":{"type":"string"}},{"name":"examinee_id","in":"query","required":false,"example":"b2c3d4e5-f6a7-8b9c-0d1e-f2a3b4c5d6e7","description":"Only return emails sent to this examinee","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"example":"invitation","description":"Only return emails of this kind","schema":{"type":"string","enum":["invitation"]}}],"responses":{"200":{"description":"Including emails attached to the exam itself","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/email"}},"meta":{"$ref":"#/components/schemas/pagination_meta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"unauthorized","status_code":401}}},"schema":{"$ref":"#/components/schemas/error"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"examples":{"invalid_schema":{"value":{"error":"invalid_schema","status_code":422,"messages":["type must be one of: invitation"]}}},"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/emails/{id}":{"parameters":[{"name":"id","in":"path","required":true,"example":"a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6","description":"The id of the email in Evalmee","schema":{"type":"string"}}],"get":{"summary":"Retrieve an email","tags":["Emails"],"description":"Retrieve a single email sent to one of your examinees, with its delivery status.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/email"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"unauthorized","status_code":401}}},"schema":{"$ref":"#/components/schemas/error"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/exams/{exam_id}/exam_attempts":{"parameters":[{"name":"exam_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List all exam attempts","tags":["Exam Attempts"],"description":"List all exam attempts for a given exam.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/exam_attempt"}},"meta":{"$ref":"#/components/schemas/pagination_meta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"unauthorized","status_code":401}}},"schema":{"$ref":"#/components/schemas/error"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/exams/{exam_id}/results":{"get":{"summary":"List all exam results","tags":["Exam Results"],"description":"List all results of examinees for a given exam.\n","parameters":[{"name":"exam_id","in":"path","required":true,"example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"examples":{"Simple":{"value":{"data":[{"examinee_id":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","exam_attempts":{"data":[{"id":"b2c3d4e5-f6a7-4b8c-9d0e-f1f2f3f4f5f6","status":"graded","grade":75,"grade_locked":false,"grade_scale":100,"started_at":"2025-05-12T07:46:28.576Z","finished_at":"2025-05-12T08:46:28.576Z","web_app_url":"https://app.evalmee.com/xxxxx","grades_by_criteria":[],"exam_session":{"id":"a1B2c3d4e5","name":"Session 1","start_at":"2025-01-01T00:00:00Z","scheduled_end_at":"2025-06-01T00:00:00Z","groups":[],"web_app_examinee_enrollment_url":"https://app.evalmee.com/join/a1B2c3d4e5-exam-name-session-1","allow_self_enrollment":"none","links":{"self":"https://app.evalmee.com/api/public/v2/xxxxxx"}}}],"meta":{"count":1,"current_page":1,"next_page":null,"prev_page":null,"total_count":1,"total_pages":1,"links":{"first":"https://app.evalmee.com/api/public/v2/xxxxxx","last":"https://app.evalmee.com/api/public/v2/xxxxxx"}}},"examinee":{"id":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","first_name":"John","last_name":"Doe","email":"john.doe@example.com","links":{"self":"https://app.evalmee.com/api/public/v2/xxxxxx"}},"grade":75,"grade_locked":false,"grade_scale":100,"status":"graded","grades_by_criteria":[],"selected_exam_attempt_id":"b2c3d4e5-f6a7-4b8c-9d0e-f1f2f3f4f5f6"}],"meta":{"count":1,"current_page":1,"next_page":null,"prev_page":null,"total_count":1,"total_pages":1,"links":{"first":"https://app.evalmee.com/api/public/v2/xxxxxx","last":"https://app.evalmee.com/api/public/v2/xxxxxx"}}}},"With a locked grade (pending subscription)":{"value":{"data":[{"examinee_id":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","grade":null,"grade_locked":true,"grade_scale":100,"status":"graded","grades_by_criteria":[{"code":"CE1","name":"Planning","description":"Develops comprehensive project plans with realistic timelines","grade":null,"grade_locked":true,"grade_scale":10,"question_ids":["d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a"]}],"selected_exam_attempt_id":"b2c3d4e5-f6a7-4b8c-9d0e-f1f2f3f4f5f6"}],"meta":{"count":1,"current_page":1,"next_page":null,"prev_page":null,"total_count":1,"total_pages":1,"links":{"first":"https://app.evalmee.com/api/public/v2/xxxxxx","last":"https://app.evalmee.com/api/public/v2/xxxxxx"}}}},"With grades by criteria":{"value":{"data":[{"examinee_id":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","exam_attempts":{"data":[{"id":"b2c3d4e5-f6a7-4b8c-9d0e-f1f2f3f4f5f6","status":"graded","grade":77.78,"grade_locked":false,"grade_scale":100,"started_at":"2025-05-12T07:46:28.576Z","finished_at":"2025-05-12T08:46:28.576Z","web_app_url":"https://app.evalmee.com/xxxxx","grades_by_criteria":[{"code":"CE1","name":"Planning","description":"Develops comprehensive project plans with realistic timelines","grade":8,"grade_locked":false,"grade_scale":10,"question_ids":["d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a","77434259-a647-4593-bc7a-5676896c7e21"]},{"code":"CE2","name":"Risk Management","description":"Identifies and mitigates project risks proactively","grade":4,"grade_locked":false,"grade_scale":5,"question_ids":["e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8a9b"]},{"code":"_no_criterion","name":"No criterion","description":null,"grade":2,"grade_locked":false,"grade_scale":3,"question_ids":["f6a7b8c9-d0e1-4f2a-3b4c-5d6e7f8a9b0c"]}],"exam_session":{"id":"a1B2c3d4e5","name":"Session 1","start_at":"2025-01-01T00:00:00Z","scheduled_end_at":"2025-06-01T00:00:00Z","groups":[],"web_app_examinee_enrollment_url":"https://app.evalmee.com/join/a1B2c3d4e5-exam-name-session-1","allow_self_enrollment":"none","links":{"self":"https://app.evalmee.com/api/public/v2/xxxxxx"}}}],"meta":{"count":1,"current_page":1,"next_page":null,"prev_page":null,"total_count":1,"total_pages":1,"links":{"first":"https://app.evalmee.com/api/public/v2/xxxxxx","last":"https://app.evalmee.com/api/public/v2/xxxxxx"}}},"examinee":{"id":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","first_name":"John","last_name":"Doe","email":"john.doe@example.com","links":{"self":"https://app.evalmee.com/api/public/v2/xxxxxx"}},"grade":77.78,"grade_locked":false,"grade_scale":100,"status":"graded","grading_mode":"global","grades_by_criteria":[{"code":"CE1","name":"Planning","description":"Develops comprehensive project plans with realistic timelines","grading_instruction":"Check milestone definitions and resource allocation","grade":8,"grade_locked":false,"grade_scale":10,"question_ids":["d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a"]},{"code":"CE2","name":"Risk Management","description":"Identifies and mitigates project risks proactively","grading_instruction":"Evaluate risk identification and mitigation strategies","grade":4,"grade_locked":false,"grade_scale":5,"question_ids":["e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8a9b"]},{"code":"_no_criterion","name":"No criterion","description":null,"grading_instruction":null,"grade":2,"grade_locked":false,"grade_scale":3,"question_ids":["f6a7b8c9-d0e1-4f2a-3b4c-5d6e7f8a9b0c"]}],"selected_exam_attempt_id":"b2c3d4e5-f6a7-4b8c-9d0e-f1f2f3f4f5f6"}],"meta":{"count":1,"current_page":1,"next_page":null,"prev_page":null,"total_count":1,"total_pages":1,"links":{"first":"https://app.evalmee.com/api/public/v2/xxxxxx","last":"https://app.evalmee.com/api/public/v2/xxxxxx"}}}}},"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/exam_result"}},"meta":{"$ref":"#/components/schemas/pagination_meta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"unauthorized","status_code":401}}},"schema":{"$ref":"#/components/schemas/error"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/exams/{exam_id}/exam_sessions/{exam_session_id}/invitations":{"parameters":[{"name":"exam_id","in":"path","required":true,"example":"a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6","description":"The id of the exam in Evalmee","schema":{"type":"string"}},{"name":"exam_session_id","in":"path","required":true,"example":"a1B2c3d4e5","description":"The id of the exam session in Evalmee","schema":{"type":"string"}}],"post":{"summary":"Send invitations to a whole exam session","tags":["Invitations"],"description":"Send an invitation email to every examinee of a given exam session.\n\nAnswers with one entry per recipient and an `errors_count`, like the other\nbulk endpoints.\n\nSending again is how a reminder is issued: each send creates its own invitation,\nso the full history stays readable through the emails endpoint. Provide `content_override`\nto give the reminder a body of its own.\n","parameters":[],"responses":{"200":{"description":"Success sending a single invitation per examinee","content":{"application/json":{"schema":{"type":"object","properties":{"errors_count":{"type":"integer"},"data":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"status":{"type":"string","enum":["error","created","updated","deleted","ignored"]},"error":{"$ref":"#/components/schemas/error"},"data":{"type":"object","nullable":true,"allOf":[{"$ref":"#/components/schemas/email"}]}},"required":["index","status"]}}},"required":["errors_count","data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"unauthorized","status_code":401}}},"schema":{"$ref":"#/components/schemas/error"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"examples":{"invalid_schema":{"value":{"error":"invalid_schema","status_code":422,"messages":["content_override must be filled"]}}},"schema":{"$ref":"#/components/schemas/error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content_override":{"description":"The body of the invitation email, overriding the exam's default convocation\ntemplate for this send only. Omit the key to use the exam's default — an\nempty string is rejected rather than treated as \"no override\".\n\nAvailable placeholders:\n- `{{first_name}}` — The examinee's first name (also: `{{prenom}}`, `{{prénom}}`)\n- `{{last_name}}` — The examinee's last name (also: `{{nom}}`, `{{nom_de_famille}}`)\n- `{{full_name}}` — The examinee's first and last name (also: `{{nom_entier}}`, `{{nom_complet}}`)\n- `{{email}}` — The examinee's email address (also: `{{mail}}`, `{{e-mail}}`)\n- `{{student_id}}` — The examinee's student id in the school (also: `{{identifiant}}`, `{{id}}`)\n- `{{quiz}}` — The name of the exam (also: `{{quiz_name}}`, `{{exam}}`, `{{examen}}`)\n- `{{lien_de_connexion}}` — A link to the exam, labelled in the examinee's own language\n- `{{lien_de_connexion_fr}}` — A link to the exam, labelled in French\n- `{{lien_de_connexion_en}}` — A link to the exam, labelled in English\n- `{{note}}` — The examinee's grade, or a placeholder when it is withheld (also: `{{grade}}`)\n- `{{date}}` — The day the exam session opens (also: `{{start_date}}`)\n- `{{date_de_fin}}` — The day the exam session closes, time accommodation included (also: `{{stop_date}}`)\n- `{{debut}}` — The time the exam session opens (also: `{{début}}`, `{{heure_de_debut}}`, `{{heure_de_début}}`, `{{start}}`, `{{start_time}}`)\n- `{{fin}}` — The time the exam session closes, time accommodation included (also: `{{heure_de_fin}}`, `{{end}}`, `{{end_time}}`)\n- `{{publication}}` — The time the grades are published (also: `{{heure_de_publication}}`, `{{publish}}`, `{{publish_time}}`)\n- `{{fuseau_horaire}}` — The time zone the exam times are expressed in (also: `{{time_zone}}`)\n- `{{duree}}` — How long the examinee has to answer, time accommodation included (also: `{{durée}}`, `{{duration}}`, `{{length}}`)","example":"Hello {{first_name}}, your exam starts at {{debut}}. {{lien_de_connexion}}","type":"string","minLength":1}}},"examples":{"Basic":{"summary":"Send the exam's default convocation","value":{}},"With custom content":{"summary":"Send a reminder with its own body","value":{"content_override":"Hello {{first_name}}, your exam starts at {{debut}}. {{lien_de_connexion}}"}}}}}}}},"/exams/{exam_id}/exam_sessions":{"parameters":[{"name":"exam_id","in":"path","required":true,"example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","description":"The id of the exam in Evalmee","schema":{"type":"string"}}],"get":{"summary":"List all exam sessions","tags":["Exam Sessions"],"description":"List all exam sessions for a given exam.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/exam_session"}},"meta":{"$ref":"#/components/schemas/pagination_meta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"unauthorized","status_code":401}}},"schema":{"$ref":"#/components/schemas/error"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}}}},"post":{"summary":"Create an exam session","tags":["Exam Sessions"],"description":"Create a new exam session for a given exam, with scheduling, group restrictions, and self-enrollment options.\n","parameters":[],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/exam_session"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"unauthorized","status_code":401}}},"schema":{"$ref":"#/components/schemas/error"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"examples":{"invalid_schema":{"value":{"error":"invalid_schema","status_code":422,"messages":["name must be filled","scheduled_end_at must be a date time","allow_self_enrollment must be one of: none, all, in_school","groups must be an array"]}}},"schema":{"$ref":"#/components/schemas/error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"The name of the exam session","example":"Session 1"},"start_at":{"description":"The start date and time of the exam session (ISO 8601).\nLeave empty if you don't want to schedule a start date.","example":"2025-01-01T00:00:00Z","type":"string","format":"date-time","nullable":true},"scheduled_end_at":{"description":"The scheduled end date and time of the exam session (ISO 8601).\nLeave empty if you don't want to schedule an end date.","example":"2025-01-01T00:00:00Z","type":"string","format":"date-time","nullable":true},"allow_self_enrollment":{"description":"Whether to allow examinees to enroll themselves in the exam session.\n\n- `none` = forbid self enrollment\n\n- `all` = allow all examinees to enroll themselves\n\n- `in_school` = allow only examinees with an email matching the school domain to enroll themselves","example":"none","type":"string","minLength":1,"enum":["none","all","in_school"]},"groups":{"description":"The list of groups allowed to access the exam session.\nLeave empty if all exam's examinees are allowed to access this exam session.","example":["group1","group2"],"type":"array","items":{"type":"string"}}}},"examples":{"Basic":{"summary":"Basic ExamSession","value":{"name":"My Session"}},"With details":{"summary":"ExamSession with details","value":{"name":"My Session","groups":["Group 1","Group 2"],"allow_self_enrollment":"all","start_at":"2025-01-01T00:00:00Z","scheduled_end_at":"2025-01-01T00:00:00Z"}}}}}}}},"/exams/{exam_id}/exam_sessions/{id}":{"parameters":[{"name":"exam_id","in":"path","required":true,"example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","description":"The id of the exam in Evalmee","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"example":"a1B2c3d4e5","description":"The id of the exam session in Evalmee","schema":{"type":"string"}}],"get":{"summary":"Retrieve an exam session","tags":["Exam Sessions"],"description":"Retrieve a given exam session, including scheduling, group restrictions, and self-enrollment options.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/exam_session"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}}}},"patch":{"summary":"Update an exam session","tags":["Exam Sessions"],"description":"Update the properties of a given exam session, including scheduling, group restrictions, and self-enrollment options.\n","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/exam_session"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"examples":{"invalid_schema":{"value":{"error":"invalid_schema","status_code":422,"messages":["name must be filled","scheduled_end_at must be a date time","allow_self_enrollment must be one of: none, all, in_school","groups must be an array"]}}},"schema":{"$ref":"#/components/schemas/error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"The name of the exam session","example":"Session 1"},"start_at":{"description":"The start date and time of the exam session (ISO 8601).\nLeave empty if you don't want to schedule a start date.","example":"2025-01-01T00:00:00Z","type":"string","format":"date-time","nullable":true},"scheduled_end_at":{"description":"The scheduled end date and time of the exam session (ISO 8601).\nLeave empty if you don't want to schedule an end date.","example":"2025-01-01T00:00:00Z","type":"string","format":"date-time","nullable":true},"allow_self_enrollment":{"description":"Whether to allow examinees to enroll themselves in the exam session.\n\n- `none` = forbid self enrollment\n\n- `all` = allow all examinees to enroll themselves\n\n- `in_school` = allow only examinees with an email matching the school domain to enroll themselves","example":"none","type":"string","minLength":1,"enum":["none","all","in_school"]},"groups":{"description":"The list of groups allowed to access the exam session.\nLeave empty if all exam's examinees are allowed to access this exam session.","example":["group1","group2"],"type":"array","items":{"type":"string"}}}},"examples":{"Basic":{"summary":"Basic ExamSession","value":{"name":"My Session"}},"With details":{"summary":"ExamSession with details","value":{"name":"My Session","groups":["Group 1","Group 2"],"allow_self_enrollment":"all","start_at":"2025-01-01T00:00:00Z","scheduled_end_at":"2025-01-01T00:00:00Z"}}}}}}}},"/exams/{exam_id}/examinees/{examinee_id}/invitations":{"parameters":[{"name":"exam_id","in":"path","required":true,"example":"a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6","description":"The id of the exam in Evalmee","schema":{"type":"string"}},{"name":"examinee_id","in":"path","required":true,"example":"b2c3d4e5-f6a7-8b9c-0d1e-f2a3b4c5d6e7","description":"The id of the examinee in Evalmee","schema":{"type":"string"}},{"name":"exam_session_id","in":"query","required":true,"example":"a1B2c3d4e5","description":"The id of the exam session the invitation is about. Required even though the\nrecipient is fixed: an examinee can sit the same exam in several sessions.\n","schema":{"type":"string"}}],"post":{"summary":"Send an invitation to a single examinee","tags":["Invitations"],"description":"Send an invitation email to one examinee for a given exam session.\n\nSending again is how a reminder is issued: each send creates its own invitation,\nso the full history stays readable through the emails endpoint. Provide `content_override`\nto give the reminder a body of its own.\n","parameters":[],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/email"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"unauthorized","status_code":401}}},"schema":{"$ref":"#/components/schemas/error"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"examples":{"Invalid content override":{"value":{"error":"invalid_schema","status_code":422,"messages":["content_override must be filled"]}},"Missing exam session":{"value":{"error":"invalid_schema","status_code":422,"messages":["exam_session_id is missing"]}}},"schema":{"$ref":"#/components/schemas/error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content_override":{"description":"The body of the invitation email, overriding the exam's default convocation\ntemplate for this send only. Omit the key to use the exam's default — an\nempty string is rejected rather than treated as \"no override\".\n\nAvailable placeholders:\n- `{{first_name}}` — The examinee's first name (also: `{{prenom}}`, `{{prénom}}`)\n- `{{last_name}}` — The examinee's last name (also: `{{nom}}`, `{{nom_de_famille}}`)\n- `{{full_name}}` — The examinee's first and last name (also: `{{nom_entier}}`, `{{nom_complet}}`)\n- `{{email}}` — The examinee's email address (also: `{{mail}}`, `{{e-mail}}`)\n- `{{student_id}}` — The examinee's student id in the school (also: `{{identifiant}}`, `{{id}}`)\n- `{{quiz}}` — The name of the exam (also: `{{quiz_name}}`, `{{exam}}`, `{{examen}}`)\n- `{{lien_de_connexion}}` — A link to the exam, labelled in the examinee's own language\n- `{{lien_de_connexion_fr}}` — A link to the exam, labelled in French\n- `{{lien_de_connexion_en}}` — A link to the exam, labelled in English\n- `{{note}}` — The examinee's grade, or a placeholder when it is withheld (also: `{{grade}}`)\n- `{{date}}` — The day the exam session opens (also: `{{start_date}}`)\n- `{{date_de_fin}}` — The day the exam session closes, time accommodation included (also: `{{stop_date}}`)\n- `{{debut}}` — The time the exam session opens (also: `{{début}}`, `{{heure_de_debut}}`, `{{heure_de_début}}`, `{{start}}`, `{{start_time}}`)\n- `{{fin}}` — The time the exam session closes, time accommodation included (also: `{{heure_de_fin}}`, `{{end}}`, `{{end_time}}`)\n- `{{publication}}` — The time the grades are published (also: `{{heure_de_publication}}`, `{{publish}}`, `{{publish_time}}`)\n- `{{fuseau_horaire}}` — The time zone the exam times are expressed in (also: `{{time_zone}}`)\n- `{{duree}}` — How long the examinee has to answer, time accommodation included (also: `{{durée}}`, `{{duration}}`, `{{length}}`)","example":"Hello {{first_name}}, your exam starts at {{debut}}. {{lien_de_connexion}}","type":"string","minLength":1}}},"examples":{"Basic":{"summary":"Send the exam's default convocation","value":{}},"With custom content":{"summary":"Send a reminder with its own body","value":{"content_override":"Hello {{first_name}}, your exam starts at {{debut}}. {{lien_de_connexion}}"}}}}}}}},"/exams/{exam_id}/examinees":{"parameters":[{"name":"exam_id","in":"path","required":true,"example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","description":"The id of the exam in Evalmee","schema":{"type":"string"}}],"get":{"summary":"List all examinees","tags":["Examinees"],"description":"List all examinees enrolled in a given exam. \n\nExaminees can be assigned to one or more groups.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/examinee"}},"meta":{"$ref":"#/components/schemas/pagination_meta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"unauthorized","status_code":401}}},"schema":{"$ref":"#/components/schemas/error"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}}}},"post":{"summary":"Enroll an examinee","tags":["Examinees"],"description":"Enroll an examinee into a given exam. The examinee account is created automatically if it does not exist.\nNo email is sent upon enrollment.\n","parameters":[],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/examinee"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"unauthorized","status_code":401}}},"schema":{"$ref":"#/components/schemas/error"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"examples":{"invalid_schema":{"value":{"error":"invalid_schema","status_code":422,"messages":["email must be a valid email address"]}}},"schema":{"$ref":"#/components/schemas/error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"description":"The first name of the examinee","example":"John","type":"string","minLength":1},"last_name":{"description":"The last name of the examinee","example":"Doe","type":"string","minLength":1},"groups":{"description":"The list of groups the examinee belongs to. Replace the existing groups if any. Skip to keep the existing groups.","example":["Group 1","Group 2"],"type":"array","items":{"type":"string"}},"id":{"description":"The id of the examinee","example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","type":"string","minLength":1,"pattern":"^[a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab][a-f0-9]{3}-?[a-f0-9]{12}$"},"email":{"description":"The email of the examinee","example":"john.doe@example.com","type":"string","minLength":1,"format":"email"},"mark_for_destruction":{"description":"If true, the examinee will be deleted.","example":false,"type":"boolean"},"groups_to_add":{"description":"The list of groups to add to the examinee.","example":["Group 3","Group 4"],"type":"array","items":{"type":"string"}},"groups_to_remove":{"description":"The list of groups to remove from the examinee.","example":["Group 1","Group 2"],"type":"array","items":{"type":"string"}}}},"examples":{"Basic":{"summary":"Enroll an examinee","value":{"email":"john.doe@example.com","first_name":"John","last_name":"Doe"}},"With groups":{"summary":"Enroll an examinee with groups","value":{"email":"john.doe@example.com","first_name":"John","last_name":"Doe"}}}}}}},"patch":{"summary":"Batch manage examinees","tags":["Examinees"],"description":"Batch enroll, update, or unenroll examinees for a given exam in a single operation. \n \nExaminee accounts are created automatically if needed.\n\nNo email is sent upon enrollment.\n","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"errors_count":{"type":"integer"},"data":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"status":{"type":"string","enum":["error","created","updated","deleted","ignored"]},"error":{"$ref":"#/components/schemas/error"},"data":{"type":"object","nullable":true,"allOf":[{"$ref":"#/components/schemas/examinee"}]}},"required":["index","status"]}}},"required":["errors_count","data"]}}}},"207":{"description":"Multi-Status","content":{"application/json":{"schema":{"type":"object","properties":{"errors_count":{"type":"integer"},"data":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"status":{"type":"string","enum":["error","created","updated","deleted","ignored"]},"error":{"$ref":"#/components/schemas/error"},"data":{"type":"object","nullable":true,"allOf":[{"$ref":"#/components/schemas/examinee"}]}},"required":["index","status"]}}},"required":["errors_count","data"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"unauthorized","status_code":401}}},"schema":{"$ref":"#/components/schemas/error"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"examples":{"Partial failure":{"value":{"errors_count":3,"data":[{"index":2,"status":"error","error":{"error":"protected_field","status_code":422,"messages":["Can't update user email"]}},{"index":3,"status":"error","error":{"error":"not_found","status_code":422,"messages":["examinee not found"]}},{"index":4,"status":"error","error":{"error":"not_found","status_code":422,"messages":["examinee not found"]}}]}},"invalid_schema":{"value":{"error":"invalid_schema","status_code":422,"messages":["examinees is missing"]}}},"schema":{"oneOf":[{"type":"object","properties":{"errors_count":{"type":"integer"},"data":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"status":{"type":"string","enum":["error","created","updated","deleted","ignored"]},"error":{"$ref":"#/components/schemas/error"},"data":{"type":"object","nullable":true,"allOf":[{"$ref":"#/components/schemas/examinee"}]}},"required":["index","status"]}}},"required":["errors_count","data"]},{"$ref":"#/components/schemas/error"}]}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"examinees":{"type":"array","items":{"type":"object","properties":{"first_name":{"description":"The first name of the examinee","example":"John","type":"string","minLength":1},"last_name":{"description":"The last name of the examinee","example":"Doe","type":"string","minLength":1},"groups":{"description":"The list of groups the examinee belongs to. Replace the existing groups if any. Skip to keep the existing groups.","example":["Group 1","Group 2"],"type":"array","items":{"type":"string"}},"id":{"description":"The id of the examinee","example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","type":"string","minLength":1,"pattern":"^[a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab][a-f0-9]{3}-?[a-f0-9]{12}$"},"email":{"description":"The email of the examinee","example":"john.doe@example.com","type":"string","minLength":1,"format":"email"},"mark_for_destruction":{"description":"If true, the examinee will be deleted.","example":false,"type":"boolean"},"groups_to_add":{"description":"The list of groups to add to the examinee.","example":["Group 3","Group 4"],"type":"array","items":{"type":"string"}},"groups_to_remove":{"description":"The list of groups to remove from the examinee.","example":["Group 1","Group 2"],"type":"array","items":{"type":"string"}}},"minLength":1,"maxLength":50}},"allow_partial_success":{"description":"If false, no examinees will be created if one or more fail to be created.","example":false,"type":"boolean"}},"required":["examinees"]},"examples":{"Enroll examinees":{"summary":"Enroll two examinees to the exam","value":{"examinees":[{"email":"john.doe.student@example.com","first_name":"John","last_name":"Doe"},{"email":"jane.doe.student@example.com","first_name":"Jane","last_name":"Doe"}]}},"Enroll examinees with groups":{"summary":"Enroll two examinees to the exam with groups","value":{"examinees":[{"email":"john.doe.student@example.com","first_name":"John","last_name":"Doe","groups":["Group 1"]},{"email":"jane.doe.student@example.com","first_name":"Jane","last_name":"Doe","groups":["Group 2"]}]}},"Update examinees groups":{"summary":"Replace the groups of two examinees already in the exam","value":{"examinees":[{"email":"john.doe.student@example.com","groups":["Group 3"]},{"email":"jane.doe.student@example.com","groups":["Group 4"]}]}},"Update groups of examinees":{"summary":"Add and remove groups from two examinees already in the exam","value":{"examinees":[{"email":"john.doe.student@example.com","groups_to_add":["Group 3"],"groups_to_remove":["Group 1"]},{"email":"jane.doe.student@example.com","groups_to_add":["Group 4"],"groups_to_remove":["Group 2"]}]}},"Unenroll two examinees":{"summary":"Uneroll two examinees from the exam","value":{"examinees":[{"email":"john.doe.student@example.com","mark_for_destruction":true},{"email":"jane.doe.student@example.com","mark_for_destruction":true}]}}}}}}}},"/exams/{exam_id}/examinees/{id}":{"parameters":[{"name":"exam_id","in":"path","required":true,"example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","description":"The id of the exam in Evalmee","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","description":"The id of the examinee in this exam in Evalmee","schema":{"type":"string"}}],"get":{"summary":"Retrieve an examinee","tags":["Examinees"],"description":"Retrieve a given examinee for a given exam, including their group assignments.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/examinee"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}}}},"patch":{"summary":"Update an examinee","tags":["Examinees"],"description":"Update the information or group assignments of a given examinee for a given exam.","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/examinee"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"examples":{"invalid_schema":{"value":{"error":"invalid_schema","status_code":422,"messages":["first_name must be filled"]}}},"schema":{"$ref":"#/components/schemas/error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"description":"The first name of the examinee","example":"John","type":"string","minLength":1},"last_name":{"description":"The last name of the examinee","example":"Doe","type":"string","minLength":1},"groups":{"description":"The list of groups the examinee belongs to. Replace the existing groups if any. Skip to keep the existing groups.","example":["Group 1","Group 2"],"type":"array","items":{"type":"string"}},"id":{"description":"The id of the examinee","example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","type":"string","minLength":1,"pattern":"^[a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab][a-f0-9]{3}-?[a-f0-9]{12}$"},"email":{"description":"The email of the examinee","example":"john.doe@example.com","type":"string","minLength":1,"format":"email"},"mark_for_destruction":{"description":"If true, the examinee will be deleted.","example":false,"type":"boolean"},"groups_to_add":{"description":"The list of groups to add to the examinee.","example":["Group 3","Group 4"],"type":"array","items":{"type":"string"}},"groups_to_remove":{"description":"The list of groups to remove from the examinee.","example":["Group 1","Group 2"],"type":"array","items":{"type":"string"}}}},"examples":{"Name update":{"summary":"Update an examinee name","value":{"first_name":"Examinee","last_name":"Doe"}},"Replace groups":{"summary":"Replace the groups of an examinee","value":{"groups":["Group 3"]}},"Add and remove groups":{"summary":"Add and remove groups from an examinee","value":{"groups_to_add":["Group 3"],"groups_to_remove":["Group 1"]}}}}}}},"delete":{"summary":"Unenroll an examinee","tags":["Examinees"],"description":"Unenroll a given examinee from a given exam. All associated attempts and results are deleted, but the examinee account is preserved.\n","responses":{"204":{"description":"Success"},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/exams":{"get":{"summary":"List all exams","tags":["Exams"],"description":"List all exams in your organization.\n","parameters":[{"name":"per_page","in":"query","required":false,"description":"Number of items per page","schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success with string per_page parameter","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/exam"}},"meta":{"$ref":"#/components/schemas/pagination_meta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"unauthorized","status_code":401}}},"schema":{"$ref":"#/components/schemas/error"}}}}}},"post":{"summary":"Create an exam","tags":["Exams"],"description":"Create a new exam with optional settings.\n","parameters":[],"responses":{"201":{"description":"Created keeping the defaults it was not given","content":{"application/json":{"examples":{"Without assessment criteria":{"value":{"id":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","name":"My exam","grade_scale":15,"grading_mode":"global","time_limit":7200,"time_accommodation":true,"random_sections":true,"random_questions":true,"random_exercises":true,"random_choices":true,"web_app_url":"https://app.evalmee.com/evalmee_editor/1/evalmee_editor","exam_sessions":{"data":[{"id":"a1B2c3d4e5","name":"My general session","start_at":"2025-01-01T08:00:00Z","scheduled_end_at":null,"allow_self_enrollment":"none","web_app_examinee_enrollment_url":"https://app.evalmee.com/join/a1B2c3d4e5-my-exam-my-general-session","groups":[],"links":{"self":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6/exam_sessions/a1B2c3d4e5","exam":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6"}}],"meta":{"count":1,"current_page":1,"next_page":null,"prev_page":null,"total_count":1,"total_pages":1,"links":{"first":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6/exam_sessions?page=1","last":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6/exam_sessions?page=1"}}},"assessment_criteria":{"data":[],"meta":{"count":0,"current_page":1,"next_page":null,"prev_page":null,"total_count":0,"total_pages":0,"links":{"first":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6/assessment_criteria?page=1","last":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6/assessment_criteria?page=1"}}},"links":{"self":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","exam_attempts":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6/exam_attempts","exam_results":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6/results","examinees":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6/examinees"}}},"With assessment criteria":{"value":{"id":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","name":"Exam with criteria","grade_scale":20,"grading_mode":"criteria","time_limit":null,"time_accommodation":false,"random_sections":false,"random_questions":false,"random_exercises":false,"random_choices":false,"web_app_url":"https://app.evalmee.com/evalmee_editor/1/evalmee_editor","exam_sessions":{"data":[{"id":"a1B2c3d4e5","name":"Session 1","start_at":null,"scheduled_end_at":null,"allow_self_enrollment":"none","web_app_examinee_enrollment_url":"https://app.evalmee.com/join/a1B2c3d4e5-exam-with-criteria-session-1","groups":[],"links":{"self":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6/exam_sessions/a1B2c3d4e5","exam":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6"}}],"meta":{"count":1,"current_page":1,"next_page":null,"prev_page":null,"total_count":1,"total_pages":1,"links":{"first":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6/exam_sessions?page=1","last":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6/exam_sessions?page=1"}}},"assessment_criteria":{"data":[{"id":"b2c3d4e5-f6a7-4b8c-9d0e-f1f2f3f4f5f6","name":"Data collection methodology","code":"CE1.1","description":"Use of appropriate tools and methods to gather information in a structured manner","links":{"self":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6/assessment_criteria/b2c3d4e5-f6a7-4b8c-9d0e-f1f2f3f4f5f6","exam":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6"}},{"id":"c3d4e5f6-a7b8-4c9d-0e1f-f2f3f4f5f6f7","name":"Data structuring","code":"CE1.2","description":"Logical organization and relevant exploitation of collected information","links":{"self":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6/assessment_criteria/c3d4e5f6-a7b8-4c9d-0e1f-f2f3f4f5f6f7","exam":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6"}}],"meta":{"count":2,"current_page":1,"next_page":null,"prev_page":null,"total_count":2,"total_pages":1,"links":{"first":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6/assessment_criteria?page=1","last":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6/assessment_criteria?page=1"}}},"links":{"self":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","exam_attempts":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6/exam_attempts","exam_results":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6/results","examinees":"https://app.evalmee.com/api/public/v2/exams/a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6/examinees"}}}},"schema":{"$ref":"#/components/schemas/exam"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"unauthorized","status_code":401}}},"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"description":"Unprocessable Entity when setting the sender address","content":{"application/json":{"examples":{"invalid_schema":{"value":{"error":"invalid_schema","status_code":422,"messages":["name must be filled","editors must be an array","grade_scale must be a float"]}},"Malformed reply-to":{"value":{"error":"invalid_schema","status_code":422,"messages":["email_custom_instructions.email_reply_to is in invalid format"]}},"Read-only sender":{"value":{"error":"invalid_schema","status_code":422,"messages":["email_custom_instructions.email_sender is not allowed"]}}},"schema":{"$ref":"#/components/schemas/error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The name of the exam","example":"My exam","type":"string","minLength":1},"owner":{"description":"The email of the owner of the exam. An Evalmee account should exist for this email.","example":"john.doe@example.com","type":"string","minLength":1},"editors":{"description":"ALPHA: The emails of the editors of the exam. An Evalmee account should exist for each email. This attribute may be deleted in the future.","example":["john.doe@example.com","jane.doe@example.com"],"type":"array","items":{"type":"string"}},"time_limit":{"description":"The answer time limit for the exam in seconds. Must be a multiple of 60 (leave null for no time limit)","example":3600,"type":"integer","nullable":true},"time_accommodation":{"description":"Whether to enable time accommodation. Can be enabled only if a time limit is set.","example":true,"type":"boolean"},"grade_scale":{"description":"The maximum grade for the exam (default is 20.0)","example":20,"type":"number"},"random_sections":{"description":"Whether to randomize the order of sections","example":false,"type":"boolean"},"random_questions":{"description":"Whether to randomize the order of questions in an exercise (or page of questions)","example":false,"type":"boolean"},"random_exercises":{"description":"Whether to randomize the order of exercises (pages of questions)","example":false,"type":"boolean"},"grading_mode":{"description":"The grading mode for the exam. 'global' for grading criteria per question, 'criteria' for shared quiz-level assessment criteria","example":"criteria","type":"string","minLength":1,"enum":["global","criteria"]},"random_choices":{"description":"Whether to randomize the order of choices in questions","example":false,"type":"boolean"},"email_custom_instructions":{"description":"The configuration of the emails sent to the examinees of this exam.\nOnly the keys you provide are set; the others keep their current value.\nThe sender address is fixed and cannot be set here; use `email_reply_to`\nto choose where replies go.\n\nPlaceholders available in `content`:\n- `{{first_name}}` — The examinee's first name (also: `{{prenom}}`, `{{prénom}}`)\n- `{{last_name}}` — The examinee's last name (also: `{{nom}}`, `{{nom_de_famille}}`)\n- `{{full_name}}` — The examinee's first and last name (also: `{{nom_entier}}`, `{{nom_complet}}`)\n- `{{email}}` — The examinee's email address (also: `{{mail}}`, `{{e-mail}}`)\n- `{{student_id}}` — The examinee's student id in the school (also: `{{identifiant}}`, `{{id}}`)\n- `{{quiz}}` — The name of the exam (also: `{{quiz_name}}`, `{{exam}}`, `{{examen}}`)\n- `{{lien_de_connexion}}` — A link to the exam, labelled in the examinee's own language\n- `{{lien_de_connexion_fr}}` — A link to the exam, labelled in French\n- `{{lien_de_connexion_en}}` — A link to the exam, labelled in English\n- `{{note}}` — The examinee's grade, or a placeholder when it is withheld (also: `{{grade}}`)\n- `{{date}}` — The day the exam session opens (also: `{{start_date}}`)\n- `{{date_de_fin}}` — The day the exam session closes, time accommodation included (also: `{{stop_date}}`)\n- `{{debut}}` — The time the exam session opens (also: `{{début}}`, `{{heure_de_debut}}`, `{{heure_de_début}}`, `{{start}}`, `{{start_time}}`)\n- `{{fin}}` — The time the exam session closes, time accommodation included (also: `{{heure_de_fin}}`, `{{end}}`, `{{end_time}}`)\n- `{{publication}}` — The time the grades are published (also: `{{heure_de_publication}}`, `{{publish}}`, `{{publish_time}}`)\n- `{{fuseau_horaire}}` — The time zone the exam times are expressed in (also: `{{time_zone}}`)\n- `{{duree}}` — How long the examinee has to answer, time accommodation included (also: `{{durée}}`, `{{duration}}`, `{{length}}`)","example":{"convocation_subject":"Exam | Mathematics","content":"Hello {{first_name}}, your exam starts at {{debut}}. {{lien_de_connexion}}"},"type":"object","properties":{"content":{"type":"string","minLength":1},"subject":{"type":"string","minLength":1},"convocation_subject":{"type":"string","minLength":1},"grade_subject":{"type":"string","minLength":1},"name_sender":{"type":"string","minLength":1},"name_reply_to":{"type":"string","minLength":1},"email_reply_to":{"type":"string","minLength":1}}},"exam_sessions":{"description":"The list of sessions to create for the exam. If not provided, a single session will becreated with no scheduling","example":[{"name":"My session","start_at":"2025-01-15T14:00:00Z","scheduled_end_at":"2025-01-15T16:00:00Z"},{"name":"My restricted session","groups":["Group 1"],"start_at":"2025-01-16T14:00:00Z"}],"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"The name of the exam session","example":"Session 1"},"start_at":{"description":"The start date and time of the exam session (ISO 8601).\nLeave empty if you don't want to schedule a start date.","example":"2025-01-01T00:00:00Z","type":"string","format":"date-time","nullable":true},"scheduled_end_at":{"description":"The scheduled end date and time of the exam session (ISO 8601).\nLeave empty if you don't want to schedule an end date.","example":"2025-01-01T00:00:00Z","type":"string","format":"date-time","nullable":true},"allow_self_enrollment":{"description":"Whether to allow examinees to enroll themselves in the exam session.\n\n- `none` = forbid self enrollment\n\n- `all` = allow all examinees to enroll themselves\n\n- `in_school` = allow only examinees with an email matching the school domain to enroll themselves","example":"none","type":"string","minLength":1,"enum":["none","all","in_school"]},"groups":{"description":"The list of groups allowed to access the exam session.\nLeave empty if all exam's examinees are allowed to access this exam session.","example":["group1","group2"],"type":"array","items":{"type":"string"}}}}},"assessment_criteria":{"description":"The list of assessment criteria to create for the exam. Only effective when grading_mode is set to 'criteria'.","example":[{"name":"Data collection methodology","code":"CE1.1","description":"Use of appropriate tools and methods to gather information in a structured manner"},{"name":"Data structuring","code":"CE1.2","description":"Logical organization and relevant exploitation of collected information"}],"type":"array","items":{"type":"object","properties":{"name":{"description":"The name of the assessment criterion","example":"Data collection methodology","type":"string","minLength":1},"description":{"description":"Description of the criterion","example":"Use of appropriate tools and methods to gather information in a structured manner","type":"string","nullable":true},"code":{"description":"Short code (max 10 chars, auto-generated if omitted)","example":"CE1.1","type":"string","minLength":1,"maxLength":10}},"required":["name"]}}},"required":["owner"]},"examples":{"Basic":{"summary":"Create an exam","value":{"name":"My exam","owner":"john.doe@example.com"}},"With exam sessions":{"summary":"Create an exam with exam sessions","value":{"name":"My exam","owner":"john.doe@example.com","exam_sessions":[{"name":"All students","start_at":"2025-01-01T08:00:00Z","scheduled_end_at":"2025-01-01T10:00:00Z"},{"name":"Groups 1 and 2","start_at":"2025-01-02T10:00:00Z","scheduled_end_at":"2025-01-02T12:00:00Z","groups":["Group 1","Group 2"]}]}},"With assessment criteria":{"summary":"Create an exam with assessment criteria","value":{"name":"My exam","owner":"john.doe@example.com","grading_mode":"criteria","assessment_criteria":[{"name":"Data collection methodology","code":"CE1.1","description":"Use of appropriate tools and methods to gather information in a structured manner"},{"name":"Data structuring","code":"CE1.2","description":"Logical organization and relevant exploitation of collected information"}]}},"With details":{"summary":"Create an exam with details","value":{"name":"My exam","owner":"john.doe@example.com","grade_scale":15,"time_limit":3600,"time_accommodation":true,"random_sections":true,"random_questions":true,"random_exercises":true,"random_choices":true,"exam_sessions":[{"name":"All students","start_at":"2025-01-01T08:00:00Z","scheduled_end_at":"2025-01-01T10:00:00Z"}]}}}}}}}},"/exams/{id}":{"get":{"summary":"Retrieve an exam","tags":["Exams"],"description":"Retrieve a given exam, including settings and metadata.\n","parameters":[{"name":"id","in":"path","required":true,"example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","description":"The id of the exam in Evalmee","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/exam"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}}}},"patch":{"summary":"Update an exam","tags":["Exams"],"description":"Update the properties of a given exam.\n","parameters":[{"name":"id","in":"path","required":true,"example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","description":"The id of the exam in Evalmee","schema":{"type":"string"}}],"responses":{"200":{"description":"Success updating only some email custom instructions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/exam"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"unauthorized","status_code":401}}},"schema":{"$ref":"#/components/schemas/error"}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"description":"Unprocessable Entity with a malformed reply-to email","content":{"application/json":{"examples":{"invalid_schema":{"value":{"error":"invalid_schema","status_code":422,"messages":["name must be filled","editors must be an array","grade_scale must be a float"]}},"Malformed reply-to":{"value":{"error":"invalid_schema","status_code":422,"messages":["email_custom_instructions.email_reply_to is in invalid format"]}}},"schema":{"$ref":"#/components/schemas/error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The name of the exam","example":"My exam","type":"string","minLength":1},"owner":{"description":"The email of the owner of the exam. An Evalmee account should exist for this email.","example":"john.doe@example.com","type":"string","minLength":1},"editors":{"description":"ALPHA: The emails of the editors of the exam. An Evalmee account should exist for each email. This attribute may be deleted in the future.","example":["john.doe@example.com","jane.doe@example.com"],"type":"array","items":{"type":"string"}},"time_limit":{"description":"The answer time limit for the exam in seconds. Must be a multiple of 60 (leave null for no time limit)","example":3600,"type":"integer","nullable":true},"time_accommodation":{"description":"Whether to enable time accommodation. Can be enabled only if a time limit is set.","example":true,"type":"boolean"},"grade_scale":{"description":"The maximum grade for the exam (default is 20.0)","example":20,"type":"number"},"random_sections":{"description":"Whether to randomize the order of sections","example":false,"type":"boolean"},"random_questions":{"description":"Whether to randomize the order of questions in an exercise (or page of questions)","example":false,"type":"boolean"},"random_exercises":{"description":"Whether to randomize the order of exercises (pages of questions)","example":false,"type":"boolean"},"grading_mode":{"description":"The grading mode for the exam. 'global' for grading criteria per question, 'criteria' for shared quiz-level assessment criteria","example":"criteria","type":"string","minLength":1,"enum":["global","criteria"]},"random_choices":{"description":"Whether to randomize the order of choices in questions","example":false,"type":"boolean"},"email_custom_instructions":{"description":"The configuration of the emails sent to the examinees of this exam.\nOnly the keys you provide are set; the others keep their current value.\nThe sender address is fixed and cannot be set here; use `email_reply_to`\nto choose where replies go.\n\nPlaceholders available in `content`:\n- `{{first_name}}` — The examinee's first name (also: `{{prenom}}`, `{{prénom}}`)\n- `{{last_name}}` — The examinee's last name (also: `{{nom}}`, `{{nom_de_famille}}`)\n- `{{full_name}}` — The examinee's first and last name (also: `{{nom_entier}}`, `{{nom_complet}}`)\n- `{{email}}` — The examinee's email address (also: `{{mail}}`, `{{e-mail}}`)\n- `{{student_id}}` — The examinee's student id in the school (also: `{{identifiant}}`, `{{id}}`)\n- `{{quiz}}` — The name of the exam (also: `{{quiz_name}}`, `{{exam}}`, `{{examen}}`)\n- `{{lien_de_connexion}}` — A link to the exam, labelled in the examinee's own language\n- `{{lien_de_connexion_fr}}` — A link to the exam, labelled in French\n- `{{lien_de_connexion_en}}` — A link to the exam, labelled in English\n- `{{note}}` — The examinee's grade, or a placeholder when it is withheld (also: `{{grade}}`)\n- `{{date}}` — The day the exam session opens (also: `{{start_date}}`)\n- `{{date_de_fin}}` — The day the exam session closes, time accommodation included (also: `{{stop_date}}`)\n- `{{debut}}` — The time the exam session opens (also: `{{début}}`, `{{heure_de_debut}}`, `{{heure_de_début}}`, `{{start}}`, `{{start_time}}`)\n- `{{fin}}` — The time the exam session closes, time accommodation included (also: `{{heure_de_fin}}`, `{{end}}`, `{{end_time}}`)\n- `{{publication}}` — The time the grades are published (also: `{{heure_de_publication}}`, `{{publish}}`, `{{publish_time}}`)\n- `{{fuseau_horaire}}` — The time zone the exam times are expressed in (also: `{{time_zone}}`)\n- `{{duree}}` — How long the examinee has to answer, time accommodation included (also: `{{durée}}`, `{{duration}}`, `{{length}}`)","example":{"convocation_subject":"Exam | Mathematics","content":"Hello {{first_name}}, your exam starts at {{debut}}. {{lien_de_connexion}}"},"type":"object","properties":{"content":{"type":"string","minLength":1},"subject":{"type":"string","minLength":1},"convocation_subject":{"type":"string","minLength":1},"grade_subject":{"type":"string","minLength":1},"name_sender":{"type":"string","minLength":1},"name_reply_to":{"type":"string","minLength":1},"email_reply_to":{"type":"string","minLength":1}}},"editors_to_add":{"description":"The emails of the editors to add to the exam. An Evalmee account should exist for each email.","example":["john.doe@example.com","jane.doe@example.com"],"type":"array","items":{"type":"string"}},"editors_to_remove":{"description":"The emails of the editors to remove from the exam.","example":["john.doe@example.com","jane.doe@example.com"],"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete an exam","tags":["Exams"],"description":"Delete a given exam, including all related examinees, attempts, and results.\n","parameters":[{"name":"id","in":"path","required":true,"example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","description":"The id of the exam in Evalmee","schema":{"type":"string"}}],"responses":{"204":{"description":"Success"},"404":{"description":"Not Found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"not_found","status_code":404}}},"schema":{"$ref":"#/components/schemas/error"}}}}}}},"/exams/{exam_id}/subject/import":{"parameters":[{"name":"exam_id","in":"path","example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6","description":"The id in Evalmee of the exam to import the subject to","required":true,"schema":{"type":"string"}}],"post":{"summary":"Import an exam subject","tags":["Exams"],"parameters":[],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/exam"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"unauthorized","status_code":401}}},"schema":{"$ref":"#/components/schemas/error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"examples":{"invalid_schema":{"value":{"error":"invalid_schema","status_code":422,"messages":["import_format must be one of: evalmee, amc_text"]}},"subject_not_editable_anymore":{"value":{"error":"subject_not_editable_anymore","status_code":422,"messages":[]}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"import_format":{"description":"The format of the subject to import","example":"evalmee","type":"string","minLength":1,"enum":["evalmee","amc_text"]},"content":{"description":"The content of the subject to import in the format of the import_format","example":"# Title\n1. Question\n- Choice1\n+ Choice2","type":"string","nullable":true}},"required":["import_format"]},"examples":{"Format Evalmee":{"summary":"Import an exam subject from Evalmee","value":{"import_format":"evalmee","content":"#Exam title\n1.Question\n-Choice 1\n+Choice 2"}},"Format AMC text":{"summary":"Import an exam subject from AMC text","value":{"import_format":"amc_text","content":"Title: Exam title\n** Question 1\n-Choice 1\n+Choice 2"}}}}}}}}},"servers":[{"url":"https://app.evalmee.com/api/public/v2","description":"Production API server"},{"url":"{scheme}://{host}/api/public/v2","variables":{"scheme":{"enum":["http","https"],"default":"https"},"host":{"default":"app.evalmee.com"}},"description":"Custom"}],"security":[{"oauth":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication with Client Credentials Flow","flows":{"clientCredentials":{"tokenUrl":"/api/public/auth/token","scopes":{}}}}},"schemas":{"assessment_criterion":{"type":"object","title":"Assessment Criterion","properties":{"id":{"type":"string","format":"uuid","description":"The id of the assessment criterion in Evalmee","example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6"},"name":{"type":"string","description":"The name of the assessment criterion","example":"Data collection methodology"},"code":{"type":"string","description":"Short code for the criterion (max 10 chars, auto-generated if omitted)","example":"CE1.1"},"description":{"type":"string","nullable":true,"description":"Description of the assessment criterion","example":"Use of appropriate tools and methods to gather information in a structured manner"},"links":{"$ref":"#/components/schemas/links"}},"required":["id","name","code","links"]},"criterion_grade":{"type":"object","title":"Criterion Grade","description":"Beta feature - format may change. A grade for a specific grading criterion.","x-beta":true,"properties":{"code":{"type":"string","description":"Unique identifier for the criterion","example":"CE1"},"name":{"type":"string","description":"Display name of the criterion","example":"Planning"},"description":{"type":"string","description":"Description of the criterion","example":"Develops comprehensive project plans with realistic timelines","nullable":true},"grade":{"type":"number","description":"Points earned for this criterion.\n`null` when not yet graded **or** when the grade is locked — check\n`grade_locked` to tell the two apart.\n","example":8,"nullable":true},"grade_locked":{"type":"boolean","description":"Whether this criterion's points are withheld pending a subscription.\nMirrors the parent exam result / exam attempt `grade_locked`: the\nper-criterion breakdown is masked together with the overall grade, since\nsumming it would rebuild the withheld value.\n","example":false},"grade_scale":{"type":"number","description":"Maximum points for this criterion","example":10},"question_ids":{"type":"array","items":{"type":"string"},"description":"Question UUIDs related to this criterion (single in global mode, multiple in criteria mode)","example":["d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a"]}},"required":["code","name","grade_locked","grade_scale"]},"email":{"type":"object","title":"Email","properties":{"id":{"type":"string","description":"The id of the email in Evalmee","example":"a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6"},"type":{"type":"string","description":"The kind of email that was sent\n- `invitation` = the convocation inviting an examinee to sit the exam\n","example":"invitation","enum":["invitation"]},"status":{"type":"string","description":"The delivery status reported by the email provider.\n`unknown` means no delivery event has been received yet.\n","example":"delivered","enum":["unknown","processed","dropped","deferred","bounce","delivered","open","click","spamreport","unsubscribe","group_unsubscribe","group_resubscribe"]},"created_at":{"type":"string","format":"date-time","description":"When the email was sent (ISO 8601)","example":"2025-01-01T00:00:00Z"},"links":{"$ref":"#/components/schemas/links"}},"required":["id","type","status","created_at","links"]},"error":{"type":"object","title":"Error","properties":{"error":{"type":"string","description":"Internal error code","example":"unauthorized"},"status_code":{"type":"integer","description":"Associated HTTP status code","example":401},"messages":{"type":"array","description":"Optional messages detailing the error","items":{"type":"string"}},"meta":{"description":"Optional additional data, mainly used for debugging","additionalProperties":{"type":"object"}}},"required":["error","status_code"]},"exam":{"type":"object","title":"Exam","properties":{"id":{"type":"string","description":"The id of the exam in Evalmee","example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6"},"name":{"type":"string","description":"The name of the exam","example":"My new exam"},"grade_scale":{"type":"number","description":"The maximum grade for the exam (default is 20.0)","example":20},"time_limit":{"type":"integer","description":"The answer time limit for the exam in seconds. Must be a multiple of 60","example":3600,"nullable":true},"time_accommodation":{"type":"boolean","description":"Whether time accommodation is enabled","example":false},"random_sections":{"type":"boolean","description":"Whether to randomize the order of sections","example":false},"random_exercises":{"type":"boolean","description":"Whether to randomize the order of exercises (pages of questions)","example":false},"random_questions":{"type":"boolean","description":"Whether to randomize the order of questions in an exercise (or page of questions)","example":false},"random_choices":{"type":"boolean","description":"Whether to randomize the order of choices in questions","example":false},"grading_mode":{"type":"string","description":"The grading mode for the exam","enum":["global","criteria"],"example":"global"},"web_app_url":{"type":"string","description":"The URL to access the exam in the Evalmee or Papeez web application as an owner or editor.","example":"https://app.evalmee.com/evalmee_editor/a1b2c3d4-e5f6-7a8b-9c0d-e1f2g3h4i5j6/evalmee_editor"},"email_custom_instructions":{"type":"object","description":"The configuration of the emails sent to the examinees of this exam.\n`content` supports {{token}} placeholders (for example {{first_name}} or {{lien_de_connexion}}).\n","properties":{"content":{"type":"string","description":"The default body of the convocation email","example":"Hello {{first_name}}, your exam starts at {{debut}}. {{lien_de_connexion}}"},"subject":{"type":"string","description":"The default subject of the emails sent for this exam","example":"Exam | Mathematics"},"convocation_subject":{"type":"string","description":"The subject of the convocation email","example":"Exam | Mathematics"},"grade_subject":{"type":"string","description":"The subject of the email sent when grades are published","example":"Your grade | Mathematics"},"name_sender":{"type":"string","description":"The display name the emails are sent from","example":"A teacher via Evalmee"},"email_sender":{"type":"string","readOnly":true,"description":"The address the emails are sent from. Fixed per brand, cannot be set.","example":"contact@evalmee.com"},"name_reply_to":{"type":"string","description":"The display name replies are addressed to","example":"A teacher"},"email_reply_to":{"type":"string","description":"The address replies are addressed to","example":"teacher@example.com"}}},"exam_sessions":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/exam_session"}},"meta":{"$ref":"#/components/schemas/pagination_meta"}}},"assessment_criteria":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/assessment_criterion"}},"meta":{"$ref":"#/components/schemas/pagination_meta"}}},"links":{"$ref":"#/components/schemas/links"}},"required":["id","name"]},"exam_attempt":{"type":"object","title":"Exam Attempt","properties":{"id":{"type":"string","description":"The id of the exam attempt","example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6"},"status":{"type":"string","description":"The state of the exam attempt\n- `not_answered`: The examinee has not answered the exam in this session\n- `answering`: The examinee is answering the exam in this session\n- `answered_pending_grading`: The examinee has answered and answers are not yet graded\n- `graded_pending_approval`: The examinee has answered and answers are graded but waiting for approval [This state is not yet used]\n- `graded`: The examinee has answered and answers are graded\n","example":"answered_pending_grading","enum":["not_answered","answering","answered_pending_grading","graded_pending_approval","graded"]},"grade":{"type":"number","nullable":true,"description":"The grade for the exam attempt.\n`null` when the attempt has no grade yet **or** when the grade is locked —\ncheck `grade_locked` to tell the two apart before writing to a gradebook.\n","example":95},"grade_locked":{"type":"boolean","description":"Whether the grade is withheld pending a subscription.\nWhen `true`, `grade` and every `grades_by_criteria[].grade` are `null`\nalthough the attempt has been graded: the grade exists but is not released\nyet. Do **not** record it as a zero and do **not** overwrite a previously\nsynced grade — skip the attempt and poll again once the school has\nsubscribed, at which point the same request returns the real values.\n","example":false},"grade_scale":{"type":"number","description":"The maximum grade for the exam","example":100},"started_at":{"type":"string","format":"date-time","nullable":true,"description":"The start date and time of the exam attempt"},"finished_at":{"type":"string","format":"date-time","nullable":true,"description":"The end date and time of the exam attempt"},"web_app_url":{"type":"string","description":"The URL to access the exam attempt copy in the Evalmee or Papeez web application as an exam owner or editor.","example":"https://app.evalmee.com/xxxxx"},"grades_by_criteria":{"type":"array","description":"Beta feature - format may change. Grades broken down by criterion for this exam attempt","x-beta":true,"items":{"$ref":"#/components/schemas/criterion_grade"}},"examinee":{"$ref":"#/components/schemas/examinee"},"exam_session":{"$ref":"#/components/schemas/exam_session"},"links":{"$ref":"#/components/schemas/links"}},"required":["id","status","started_at","finished_at","grade","grade_locked","grade_scale","exam_session"]},"exam_result":{"type":"object","title":"Exam Result","properties":{"examinee_id":{"type":"string","description":"The id of the examinee","example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6"},"grade":{"type":"number","description":"The final grade of the examinee.\n`null` when the examinee has no grade yet **or** when the grade is locked —\ncheck `grade_locked` to tell the two apart before writing to a gradebook.\n","example":95,"nullable":true},"grade_locked":{"type":"boolean","description":"Whether the grade is withheld pending a subscription.\nWhen `true`, `grade` and every `grades_by_criteria[].grade` are `null`\nalthough the exam has been graded: the grade exists but is not released\nyet. Do **not** record it as a zero and do **not** overwrite a previously\nsynced grade — skip the examinee and poll again once the school has\nsubscribed, at which point the same request returns the real values.\n","example":false},"grade_scale":{"type":"number","description":"The maximum grade for the exam","example":100},"selected_exam_attempt_id":{"type":"string","description":"The id of the selected exam attempt as final result","example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6"},"status":{"type":"string","description":"The status of the examinee grade\n- `not_answered_yet`: The examinee has not answered the exam\n- `answering`: The examinee is answering the exam\n- `answered_pending_grading`: The examinee has answered and answers are not yet graded\n- `graded_pending_approval`: The examinee has answered and answers are graded but waiting for approval [This status is not yet used]\n- `graded`: The examinee has answered the exam all answers are graded\n- `absent`: The examinee was absent\n","example":"answered_pending_grading","enum":["not_answered_yet","answering","answered_pending_grading","graded_pending_approval","graded","absent"]},"grading_mode":{"type":"string","description":"Beta feature. The grading mode of the exam: 'global' (per-question criteria) or 'criteria' (aggregated quiz-level criteria)","x-beta":true,"example":"global","enum":["global","criteria"]},"grades_by_criteria":{"type":"array","description":"Beta feature - format may change. Grades broken down by criterion for the selected exam attempt","x-beta":true,"items":{"$ref":"#/components/schemas/criterion_grade"}},"exam_attempts":{"type":"object","description":"The exam attempts for the examinee","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/exam_attempt"}},"meta":{"$ref":"#/components/schemas/pagination_meta"}}},"examinee":{"$ref":"#/components/schemas/examinee"},"uids_per_identity_providers":{"$ref":"#/components/schemas/uids_per_identity_providers"},"links":{"$ref":"#/components/schemas/links"}},"required":["examinee_id","grade","grade_locked","grade_scale","status"]},"exam_session":{"type":"object","title":"Exam Session","properties":{"id":{"type":"string","description":"The id of the exam session in Evalmee","example":"a1B2c3d4e5"},"name":{"type":"string","description":"The name of the exam session","example":"Session 1"},"start_at":{"type":"string","format":"date-time","nullable":true,"description":"The start date and time of the exam session (ISO 8601)","example":"2025-01-01T00:00:00Z"},"scheduled_end_at":{"type":"string","format":"date-time","nullable":true,"description":"The scheduled end date and time of the exam session (ISO 8601)","example":"2025-01-01T00:00:00Z"},"groups":{"type":"array","description":"The list of groups allowed to access the exam session. Empty if all exam's examinees are allowed to access this exam session.","items":{"type":"string"}},"web_app_examinee_enrollment_url":{"type":"string","description":"The web app url an examinee can use to self-enroll in the exam session","example":"https://app.evalmee.com/join/a1B2c3d4e5-exam-name-session-name"},"allow_self_enrollment":{"type":"string","description":"Whether to allow examinees to self-enroll in the exam session\n- `none` = no self enrollment\n- `all` = all examinees can self-enroll\n- `in_school` = only examinees with an email matching the school domain can self-enroll\n","example":"none","enum":["none","all","in_school"]},"links":{"$ref":"#/components/schemas/links"}},"required":["id","name","start_at","scheduled_end_at","web_app_examinee_enrollment_url","allow_self_enrollment","links"]},"examinee":{"type":"object","title":"Examinee","properties":{"id":{"type":"string","description":"The id of the examinee in Evalmee","example":"a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6"},"first_name":{"type":"string","nullable":true,"description":"The first name of the examinee","example":"John"},"last_name":{"type":"string","nullable":true,"description":"The last name of the examinee","example":"Doe"},"email":{"type":"string","description":"The email of the examinee","example":"john.doe@example.com"},"groups":{"type":"array","description":"The groups of the examinee","example":["Group 1","Group 2"],"items":{"type":"string"}},"uids_per_identity_providers":{"$ref":"#/components/schemas/uids_per_identity_providers"},"links":{"$ref":"#/components/schemas/links"}},"required":["id"]},"links":{"type":"object","title":"Links","additionalProperties":{"type":"string","format":"uri"},"description":"A list of API urls related to the resource","example":{"self":"https://app.evalmee.com/api/public/v2/xxxxxx"}},"pagination_meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"integer"},"next_page":{"type":"integer","nullable":true},"prev_page":{"type":"integer","nullable":true},"total_count":{"type":"integer"},"total_pages":{"type":"integer"},"links":{"type":"object","properties":{"first":{"type":"string","format":"uri"},"last":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri","nullable":true},"next":{"type":"string","format":"uri","nullable":true}},"required":["first","last"]}},"required":["count","total_count","total_pages","links"]},"uids_per_identity_providers":{"type":"array","description":"The uids per identity providers of the examinee","items":{"type":"object","properties":{"provider":{"type":"string","description":"The identity provider name","example":"evalmee"},"uid":{"type":"string","description":"The user identifier for this provider","example":"john.doe@example.com"}},"required":["provider","uid"]},"example":[{"provider":"evalmee","uid":"john.doe@example.com"},{"provider":"azure_active_directory","uid":"1234567890"}]}}}}