Skip to main content

questions-api

API Quick Start: Questions Endpoint​

Base URL: http://localhost:8081/api

Endpoints​

  • POST /questions - Creates a new question.
  • GET /questions - Lists questions. Supports ?tags=, ?q=, ?limit=, ?page=.
  • GET /questions/\{id\} - Retrieves a single question.
  • PATCH /questions/\{id\} - Partially updates a question.
  • DELETE /questions/\{id\} - Deletes a question.

Main Data Structure: Question Payload​

The payload object contains the core content of the question.

// Example of a minimal scored question
{
  "status": "published", // "draft", "in_review", "published", "archived"
  "tags": ["go", "easy"],
  "payload": {
    "type": "mcq-single", // "mcq-single" or "mcq-multi"
    "stem": "What is a goroutine?",
    "choices": [
      { "id": "c1", "text": "A lightweight thread" },
      { "id": "c2", "text": "A function" }
    ],
    "answer": {
      "correctIds": ["c1"] // Array of strings pointing to choice IDs. Required for scored questions.
    },
    "grading": { // Optional. Defaults to scored if omitted.
      "mode": "none", // "all-or-nothing" or "none"
      "weight": 0 // Weight of 0 also makes it unscored
    }
  }
}

Structured Error Response​

If you send invalid data, the API will return a 400 Bad Request with a structured JSON body detailing all the errors.

{
  "code": "validation_error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "payload.stem",
      "message": "is required"
    },
    {
      "field": "payload.choices",
      "message": "requires at least 2 options"
    }
  ]
}