Add quiz question

Requires an inactive draft. Returns the whole updated quiz.

Requires a community API key with quizzes permission; personal keys are rejected. Tenant comes from authentication. Unknown/system-owned body fields are rejected. JSON UTF-8 bodies are limited to 1 MiB. All responses use Cache-Control: no-store. Question mutations require a previous successful separate PATCH {"isActive":false}. Concurrent publication/configuration changes return 409 QUIZ_CONFLICT; fetch current detail before retrying.

POST /apis/v1/quizzes/{quizId}/questions
Path quizId: required 24 hex characters; example 507f1f77bcf86cd799439011.

Required JSON: type (single_select|multi_select|score), question (1–500 characters). Optional id (stable string ≤128; generated UUID if omitted), description (≤20000), images (≤20 URLs), options (≤100 {id,label,value}; unique ids), correctAnswer, points/timeLimit (nonnegative), teamA/teamB. Choice questions require at least one option. single_select correctAnswer is one option id; multi_select is an array of distinct option ids. Knowledge requires a nonempty valid answer. Universal choices may omit/null the answer. Score requires Universal mode, both nonempty team names, no options, and null or {teamA:integer>=0,teamB:integer>=0}. Score and choice questions cannot mix. Maximum 500 questions.

Example — Multi-select choice:

{
  "id": "q2",
  "type": "multi_select",
  "question": "Select all correct options",
  "options": [
    {
      "id": "a",
      "label": "A",
      "value": "A"
    },
    {
      "id": "b",
      "label": "B",
      "value": "B"
    }
  ],
  "correctAnswer": [
    "a",
    "b"
  ]
}

Example — Universal-only score:

{
  "id": "score1",
  "type": "score",
  "question": "Predict the result",
  "teamA": "Team A",
  "teamB": "Team B",
  "options": [],
  "correctAnswer": null
}

201 returns the whole updated quiz, including its ordered questions. Unpublish first through a separate quiz PATCH {"isActive":false}. Errors: 400 validation, 401 auth, 403 permission, 404 quiz missing, 409 QUIZ_PUBLISHED/QUIZ_CONFLICT, 413 body limit, 415 content type, 429 rate limit, 500 safe failure.

curl --location 'https://sgtr-integration.returning.ai/apis/v1/quizzes/507f1f77bcf86cd799439011/questions' \ --header 'Authorization: <api-key>' \ --header 'Content-Type: application/json' \ --data '{ "id": "q2", "type": "multi_select", "question": "Select all correct options", "options": [ { "id": "a", "label": "A", "value": "A" }, { "id": "b", "label": "B", "value": "B" } ], "correctAnswer": [ "a", "b" ] }'

{ "meta": { "status": "success", "statusCode": 201, "requestId": "req_example" }, "message": "Quiz question added success.", "data": { "_id": "507f1f77bcf86cd799439011", "serverId": "507f191e810c19729de860ea", "type": "quiz", "name": "Product knowledge", "description": "", "timezone": "UTC", "isActive": false, "viewPermission": { "roles": [], "users": [] }, "useServerTheme": true, "customThemes": [], "configuration": { "quizMode": "knowledge", "startScreen": { "title": "Start Quiz", "description": "", "startButtonText": "Start the Quiz" }, "endScreen": { "title": "You have completed this quiz.", "description": "", "completeButtonText": "Done", "reAttemptButtonText": "Try Again", "showUserScore": true }, "settings": { "showQuizProgress": false, "backNavigation": false, "questionSkips": false, "numberOfAttempts": 1, "pointsPerQuestion": 1, "answerConfiguration": { "mode": "score_only" }, "showUserScore": true, "passingMarkEnabled": true, "passingPercentage": 50 }, "questions": [ { "id": "q1", "type": "single_select", "question": "Which option is correct?", "options": [ { "id": "a", "label": "A", "value": "A" }, { "id": "b", "label": "B", "value": "B" } ], "correctAnswer": "a" }, { "id": "q2", "type": "multi_select", "question": "Select all correct options", "options": [ { "id": "a", "label": "A", "value": "A" }, { "id": "b", "label": "B", "value": "B" } ], "correctAnswer": [ "a", "b" ] } ] }, "createdAt": "2026-10-03T00:00:00.000Z", "updatedAt": "2026-10-03T00:00:00.000Z" } }

Request

Responses