curl --request POST \
--url https://api.evalezy.com/v1/exams \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"title": "Class 10 Science - Half-Yearly 2026 (Section 10-A)",
"mode": "handwritten",
"external_ref": "cbse-sci-10a-hy-2026",
"conducted_on": "2026-10-14",
"subject": "Science",
"level": "school",
"board": "CBSE",
"class": "10",
"questions": [
{
"label": "Q1",
"section": "A",
"type": "mcq_single",
"text": "Which of the following is a balanced chemical equation?",
"max_marks": 1,
"options": [
{
"label": "A",
"text": "H2 + O2 -> H2O"
},
{
"label": "B",
"text": "2H2 + O2 -> 2H2O"
},
{
"label": "C",
"text": "H2 + 2O2 -> H2O"
},
{
"label": "D",
"text": "2H2 + 2O2 -> H2O"
}
],
"correct_options": [
"B"
]
},
{
"label": "Q24",
"section": "C",
"type": "long_answer",
"text": "Explain the process of digestion of food in the human stomach. Name the enzymes involved.",
"max_marks": 3,
"expects_diagram": false,
"rubric": {
"partial_marking": true,
"criteria": [
{
"name": "Role of hydrochloric acid",
"marks": 1,
"guidance": "Acidic medium, kills germs, activates pepsin."
},
{
"name": "Enzymes named",
"marks": 1,
"keywords": [
"pepsin",
"gastric lipase"
],
"guidance": "Pepsin digests proteins; gastric lipase acts on fats."
},
{
"name": "Mucus and protection",
"marks": 1,
"guidance": "Mucus protects the inner lining from the acid."
}
]
}
}
],
"candidates": [
{
"external_id": "STU-10A-0142",
"name": "Aarav Sharma",
"roll_number": "14",
"section_or_class": "10-A"
}
],
"open": true
}
'{
"id": "3f6c1d2e-8b4a-4c7e-9a51-2d0e7b9c4f18",
"status": "open",
"mode": "handwritten",
"title": "Class 10 Science - Half-Yearly 2026 (Section 10-A)",
"external_ref": "cbse-sci-10a-hy-2026",
"conducted_on": "2026-10-14",
"subject": "Science",
"level": "school",
"board": "CBSE",
"class": "10",
"answer_language": "en",
"feedback_language": "en",
"blind": false,
"total_marks": 4,
"paper_max": 4,
"question_count": 2,
"questions": [
{
"id": "a1f0c2d4-6e8b-4a3c-9d5e-7f1b2c3d4e5f",
"label": "Q1",
"section": "A",
"max_marks": 1
},
{
"id": "b2e1d3c5-7f9a-4b4d-8e6f-0a2c3d4e5f6a",
"label": "Q24",
"section": "C",
"max_marks": 3
}
],
"candidates": [
{
"id": "c41a7e93-2f58-4b6d-8e0a-5d9f1b3c7e62",
"external_id": "STU-10A-0142",
"registration_id": "e7b3f9a1-4c2d-4e8f-a6b5-0d1c9e2f7a48"
}
],
"rubric": {
"version": 1,
"locked": false,
"questions_with_rubric": 1,
"questions_without_rubric": 1
},
"quote": {
"unit": "page",
"credits_per_page": 1,
"rate_source": "standard"
},
"opened_at": "2026-10-14T05:30:12Z",
"created_at": "2026-10-14T05:30:12Z",
"updated_at": "2026-10-14T05:30:12Z"
}{
"error": {
"code": "malformed_json",
"message": "The request body is not valid JSON for this endpoint.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "invalid_api_key",
"message": "The API key is not valid.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "insufficient_scope",
"message": "This API key lacks the evaluation:write scope.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f",
"details": {
"required_scope": "evaluation:write"
}
}
}{
"error": {
"code": "conflict",
"message": "The request conflicts with the current state.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "validation_failed",
"message": "questions[0].max_marks is required.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f",
"details": {
"errors": [
{
"field": "questions[0].max_marks",
"code": "required",
"message": "max_marks is required."
}
]
}
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests. Retry after 2 s.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}Exams
Create an exam
Creates an exam with its questions, and optionally registers candidates in the same call. The exam starts as a draft; send open: true to open it right away (or call Open an exam later).
modeishandwritten(scanned PDF copies) ortyped(answers sent as text).external_refis your own id for the exam. A second create with the same value returns 409exam_existswithdetails.exam_id, so you can safely look it up instead.- Long-answer questions with neither a rubric nor a model answer get an
auto_rubricwarning. - Only English is supported (
answer_language: en). choice_groupsis beta and enabled on request; until then it returns 422feature_not_available.
The response includes the exam’s quote (credits per page or per answer) and any warnings. Exams created through the API also appear in your dashboard, tagged Source: API.
Scope: evaluation:write
POST
/
exams
curl --request POST \
--url https://api.evalezy.com/v1/exams \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"title": "Class 10 Science - Half-Yearly 2026 (Section 10-A)",
"mode": "handwritten",
"external_ref": "cbse-sci-10a-hy-2026",
"conducted_on": "2026-10-14",
"subject": "Science",
"level": "school",
"board": "CBSE",
"class": "10",
"questions": [
{
"label": "Q1",
"section": "A",
"type": "mcq_single",
"text": "Which of the following is a balanced chemical equation?",
"max_marks": 1,
"options": [
{
"label": "A",
"text": "H2 + O2 -> H2O"
},
{
"label": "B",
"text": "2H2 + O2 -> 2H2O"
},
{
"label": "C",
"text": "H2 + 2O2 -> H2O"
},
{
"label": "D",
"text": "2H2 + 2O2 -> H2O"
}
],
"correct_options": [
"B"
]
},
{
"label": "Q24",
"section": "C",
"type": "long_answer",
"text": "Explain the process of digestion of food in the human stomach. Name the enzymes involved.",
"max_marks": 3,
"expects_diagram": false,
"rubric": {
"partial_marking": true,
"criteria": [
{
"name": "Role of hydrochloric acid",
"marks": 1,
"guidance": "Acidic medium, kills germs, activates pepsin."
},
{
"name": "Enzymes named",
"marks": 1,
"keywords": [
"pepsin",
"gastric lipase"
],
"guidance": "Pepsin digests proteins; gastric lipase acts on fats."
},
{
"name": "Mucus and protection",
"marks": 1,
"guidance": "Mucus protects the inner lining from the acid."
}
]
}
}
],
"candidates": [
{
"external_id": "STU-10A-0142",
"name": "Aarav Sharma",
"roll_number": "14",
"section_or_class": "10-A"
}
],
"open": true
}
'{
"id": "3f6c1d2e-8b4a-4c7e-9a51-2d0e7b9c4f18",
"status": "open",
"mode": "handwritten",
"title": "Class 10 Science - Half-Yearly 2026 (Section 10-A)",
"external_ref": "cbse-sci-10a-hy-2026",
"conducted_on": "2026-10-14",
"subject": "Science",
"level": "school",
"board": "CBSE",
"class": "10",
"answer_language": "en",
"feedback_language": "en",
"blind": false,
"total_marks": 4,
"paper_max": 4,
"question_count": 2,
"questions": [
{
"id": "a1f0c2d4-6e8b-4a3c-9d5e-7f1b2c3d4e5f",
"label": "Q1",
"section": "A",
"max_marks": 1
},
{
"id": "b2e1d3c5-7f9a-4b4d-8e6f-0a2c3d4e5f6a",
"label": "Q24",
"section": "C",
"max_marks": 3
}
],
"candidates": [
{
"id": "c41a7e93-2f58-4b6d-8e0a-5d9f1b3c7e62",
"external_id": "STU-10A-0142",
"registration_id": "e7b3f9a1-4c2d-4e8f-a6b5-0d1c9e2f7a48"
}
],
"rubric": {
"version": 1,
"locked": false,
"questions_with_rubric": 1,
"questions_without_rubric": 1
},
"quote": {
"unit": "page",
"credits_per_page": 1,
"rate_source": "standard"
},
"opened_at": "2026-10-14T05:30:12Z",
"created_at": "2026-10-14T05:30:12Z",
"updated_at": "2026-10-14T05:30:12Z"
}{
"error": {
"code": "malformed_json",
"message": "The request body is not valid JSON for this endpoint.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "invalid_api_key",
"message": "The API key is not valid.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "insufficient_scope",
"message": "This API key lacks the evaluation:write scope.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f",
"details": {
"required_scope": "evaluation:write"
}
}
}{
"error": {
"code": "conflict",
"message": "The request conflicts with the current state.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "validation_failed",
"message": "questions[0].max_marks is required.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f",
"details": {
"errors": [
{
"field": "questions[0].max_marks",
"code": "required",
"message": "max_marks is required."
}
]
}
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests. Retry after 2 s.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}Authorizations
Headers
Body
application/json
Response
Created