Endpoint details

Every endpoint, the scope it needs, and what to know before calling it. The API Reference section has the full field-by-field description of each one, generated from the OpenAPI document.

All paths below follow https://your-site.example/api/index.php/v1/nextexams.

Endpoints

The scope is the first check. The token owner's role is checked as well: listing attempts also needs the role's attempts.view, deleting an exam its exams.delete, and so on.

Subjects

Subjects form a tree. parent_id is 0 at the top level. path is the ids from the root down, joined by /, and level counts from 1.

Moving a subject (a PATCH with a new parent_id) rebuilds the path of its whole subtree. A move under one of its own descendants is refused.

curl -X POST https://your-site.example/api/index.php/v1/nextexams/subjects \
  -H "Authorization: Bearer nxk_your_token" \
  -H "Content-Type: application/json" \
  -d '{"title": "Algebra", "parent_id": 0, "code": "MATH-ALG"}'

{ "data": { "id": 42 } }

Questions

Lists show the bank

GET /questions lists bank questions. Two kinds are left out:

• Questions private to one exam, made in the Exam Studio with Keep in bank off. They are part of that exam and appear in its structure.
• Retired versions, kept only so old attempts can still be read. owner_exam_id is -1 on these.

GET /questions/{id} reads any question by id, whichever kind it is.

Where the answer lives

The surest way to learn a type's shape is to build one such question in the editor and read it back with GET /questions/{id}. That body is exactly what POST and PUT accept.

GET /question-types lists every question_type value, with its label in the site language. The advanced and visual types can be switched off in the App Manager; creating a new question of a switched-off type is then refused, while existing ones keep working.

Creating one

curl -X POST https://your-site.example/api/index.php/v1/nextexams/questions \
  -H "Authorization: Bearer nxk_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Two plus two",
    "question_type": "mcq_single",
    "stem": "<p>What is 2 + 2?</p>",
    "default_points": 1,
    "difficulty": 1,
    "tags": ["Arithmetic"],
    "options": [
      { "option_text": "3", "is_correct": false },
      { "option_text": "4", "is_correct": true }
    ]
  }'

tags takes tag ids, tag titles, or {id, title} objects. A title no tag has yet creates the tag.

Replacing one

Read it, change it, send the whole thing back. See Create, update and replace for why questions are replaced rather than patched, and Questions that have been answered for what Next Exams protects once attempts exist.

curl https://your-site.example/api/index.php/v1/nextexams/questions/42 \
  -H "Authorization: Bearer nxk_your_token" > q.json

# edit q.json: data.title, data.stem, …  then send data back
jq '.data' q.json | curl -X PUT https://your-site.example/api/index.php/v1/nextexams/questions/42 \
  -H "Authorization: Bearer nxk_your_token" \
  -H "Content-Type: application/json" \
  --data-binary @-

Deleting one

Exams

GET /exams/{id} returns the exam's settings and its structure:

• sections, each one either fixed (the questions placed in it, in questions) or pool (drawn at random by its pool_rules).
• in_progress_attempts: how many people are sitting it right now.

Exams are built in the Exam Studio. Through the API you can read them, publish and unpublish them, and delete them.

Attempts

GET /attempts lists attempts newest first, and filters by exam_id and status:

GET /attempts/{id} adds every response — what was answered, whether it was right, the points, and whether a person or Next Exams graded it — and the attempt's integrity signals.

Integrity signals are detection only. Focus losses, pastes, tab switches and fullscreen exits are counted, never judged. Treat them as a reason to look, not as a verdict.

A guest's attempt has user_id: null and carries the name and email the guest gave, if the exam asked for them.

Reports

All three take the exam's id in the path, and count graded attempts.

A question with low or negative discrimination is one that strong candidates get wrong as often as weak ones, which usually means it is ambiguous or mis-keyed.

Reports need the Analytics app. With it off they answer 403 APP_DISABLED.

See also

• Getting started
• Conventions and errors
• Worked example and advice
• Question bank
• Analytics and reports