Explanations API

Access step-by-step reasoning, simplified explanations, and lists of common student errors.

L3 · 10 creditsGrowth tier+

2.3.0Overview

The Explanations API generates or retrieves detailed educational explanations for a given question. This includes full step-by-step solutions, simplified summaries for quick review, and mapped common mistakes with explanations of why they are incorrect.

2.3.1Endpoint

POST/questions/{id}/explain

https://dev.aloc.com.ng/api/v1 — production base URL

2.3.2Explanation Properties

The returned explanation object matches the following schema:

PROPERTYTYPEDESCRIPTION

questionIdstringUUID of the explained question.

explanationstringFull step-by-step reasoning formatted in markdown/text.

simplifiedExplanationstringA simplified, bite-sized explanation.

commonMistakesarray [object]Array of mistakes with keys: mistake and whyWrong.

solutionImageUrlstring / nullOptional URL to a visual step solution.

sourceTypestringHow the explanation was generated (e.g. "ai").

confidencefloat (0-1)Accuracy confidence score of the solution.

needsReviewbooleanIndicates if the explanation is flagged for human review.

2.3.3Example Request/Response

POST request example

curl -X POST "https://dev.aloc.com.ng/api/v1/questions/f47ac10b-58cc-4372-a567-0e02b2c3d479/explain" \
  -H "X-API-Key: alc_live_7f3a91c2d8e4f1ab92dd"

200 OK

{
  "data": {
    "questionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "explanation": "To solve x + 3 = 8, we subtract 3 from both sides: x = 8 - 3, which gives x = 5.",
    "simplifiedExplanation": "Subtract 3 from both sides of the equation to find x = 5.",
    "commonMistakes": [
      {
        "mistake": "Adding 3 to both sides",
        "whyWrong": "Adding 3 would yield x + 6 = 11, which does not isolate x correctly."
      }
    ],
    "solutionImageUrl": null,
    "sourceType": "ai",
    "confidence": 0.99,
    "needsReview": false
  }
}