Conventions and errors

The rules every Next Exams endpoint follows, so an integration can be written once and work across all of them.

Requests

Create, update and replace

Questions are replaced, not patched. A question is saved as a whole: its options, answer key and tags go together, and anything you leave out is removed. Read the question, change what you need, and send the whole thing back. The response of GET /questions/{id} is accepted as a PUT body unchanged.

Next Exams refuses a PUT that has no options key while the question still has options (422 OPTIONS_REQUIRED). That stops an update meant to fix a typo in the title from deleting every choice. Send "options": [] if you really mean to remove them.

Responses

Success responses wrap their content in data:

{ "data": { "id": 42, "title": "Two plus two", "published": true } }

Lists add the total for paging in meta:

{ "data": [ … ], "meta": { "total": 137 } }

Paging and filters

Attempts also take exam_id and status.

Field types

• Dates are ISO 8601 in UTC, such as 2026-10-18T12:51:24Z, or null when not set. Convert to your viewers' time zone yourself.
• Numbers are numbers. Scores, points and percentages are JSON numbers, not strings.
• Every documented field is always present, with null when it has no value. A field is never silently missing.
• Responses carry exactly the documented fields. They are a stable contract, not raw database rows. Internal values such as a guest's result token or an exam's access code are never returned.

Ignore fields you do not recognise. New fields may be added in a later release; existing ones are not removed or retyped within v1.

Errors

A failure answers with an HTTP error status and an errors list, in the same shape the Joomla Web Services application uses for its own errors:

{
  "errors": [
    { "title": "The token is missing the required scope: exams:delete", "code": "MISSING_SCOPE" }
  ]
}

Match on code, never on title. The title is written for a person and may be reworded. Some codes carry extra detail in meta.

A request to an address no route matches answers 404 from Joomla itself, with a numeric code (404). Treat code as either a string or a number.

Questions that have been answered

Next Exams never changes a question under answers that were already given to it.

• Wording changes save in place. Fixing a typo in the stem is fine.
• Changes that affect grading are refused with 409 ANSWERED_NEEDS_VERSION: which option is correct, the options themselves, the answer key. Send the same body with "new_version": {"exam_ids": [3, 7]} to save it as a new version. The listed exams switch to the new version and past attempts keep grading against the old one.
• Option ids survive a save when you send them back. Keep each option's id in your PUT body and answers already given to it stay attached.

To protect against two people editing at once, send the version you read as expected_version. Next Exams answers 409 STALE if the stored version has moved on.

OpenAPI

Every Next Exams site serves its own OpenAPI 3.1 document, matching the version installed there:

https://your-site.example/media/com_nextexams/openapi.yaml

The API tokens screen links to it. It is the same document this documentation's API Reference is generated from, and it is checked against a running site on every Next Exams release: each documented response is validated against the document with undocumented fields forbidden, so the document cannot quietly drift from what the API returns.

Use it with any OpenAPI tool:

# Browse it as interactive documentation
npx @redocly/cli preview-docs https://your-site.example/media/com_nextexams/openapi.yaml

# Generate TypeScript types for a client
npx openapi-typescript https://your-site.example/media/com_nextexams/openapi.yaml -o nextexams.d.ts

The document's servers entry is templated (protocol, host, basePath), so set it to your site once and generated clients call the right address, subfolder installs included.

The older task lane

Before the REST API, integrations called the administrator JSON endpoint with a task parameter:

https://your-site.example/administrator/index.php?option=com_nextexams&format=json&task=exam.getList

It still works with the same tokens, scopes and checks, and the Next Exams admin screens use it themselves. But it returns raw records and its own envelope ({success, data}), and it cannot be described in OpenAPI, because every operation shares one address. Use the REST API for new integrations.

See also

• Getting started
• Endpoint details
• Worked example and advice