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).

mode is handwritten (scanned PDF copies) or typed (answers sent as text).
external_ref is your own id for the exam. A second create with the same value returns 409 exam_exists with details.exam_id, so you can safely look it up instead.
Long-answer questions with neither a rubric nor a model answer get an auto_rubric warning.
Only English is supported (answer_language: en).
choice_groups is beta and enabled on request; until then it returns 422 feature_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

X-API-Key

string

header

required

Your institute's API key, vak_eval_ followed by 48 hex characters. An institute admin creates keys in the dashboard under Settings -> Integrations -> API keys.

Headers

Idempotency-Key

string

Optional. Any unique string of 1-255 printable ASCII characters (a UUID works). Retrying with the same key within 48 hours replays the first response with Idempotent-Replayed: true.

Maximum string length: 255

Example:

"exam-cbse-sci-10a-2026-10-14"

Body

application/json

title

string

Exam title, up to 255 characters, no < or >.

mode

enum<string>

handwritten (scanned answer copies) or typed (answers sent as text).

Available options:

handwritten,

typed

external_ref

string

Your own id for the exam, up to 128 characters. Unique per institute: a repeat returns 409 exam_exists.

conducted_on

string<date>

Exam date, YYYY-MM-DD. Defaults to today.

subject

string

Up to 120 characters.

level

enum<string>

school (default), ug, pg or upsc.

Available options:

school,

ug,

pg,

upsc

board

string

e.g. CBSE. Up to 64 characters.

answer_language

enum<string>

Only en is supported. hi returns 422 language_not_supported.

Available options:

en,

hi

feedback_language

enum<string>

Only en is supported.

Available options:

en,

hi

instructions

string

Paper-level instructions for the evaluator, up to 4,000 characters.

blind

boolean

Hide candidate names from results and reviewers.

open

boolean

Open the exam in the same call so it accepts submissions right away.

sections

object[]

Up to 20 sections. If omitted, sections come from the questions' section values, or a single section A.

Show child attributes

questions

object[]

Up to 200 questions.

Show child attributes

choice_groups

object[]

Beta, enabled on request. Currently returns 422 feature_not_available.

Show child attributes

candidates

object[]

Up to 2,000 candidates to create (or update) and register on the exam.

Show child attributes

class

string

e.g. 10. Up to 32 characters.

Response

Created

string

status

string

mode

string

title

string

external_ref

string

conducted_on

string

subject

string

level

string

board

string

answer_language

string

feedback_language

string

instructions

string

blind

boolean

total_marks

number<double>

paper_max

number<double>

question_count

integer<int32>

dashboard_url

string

questions

object[]

Show child attributes

choice_groups

object[]

Show child attributes

candidates

object[]

Show child attributes

rubric

object

Show child attributes

quote

object

Show child attributes

stats

object

Show child attributes

warnings

object[]

Show child attributes

opened_at

string

finalized_at

string

created_at

string

updated_at

string

class

string

Overview

Endpoints

Create an exam

Authorizations

Headers

Body

Response