POST /v2/courses/{course_id}/ask

Ask a question about a course

Sends a question to the RAG pipeline scoped to a single course. Nuton retrieves the most relevant chunks from the course (and any documents it was built from), generates a grounded answer, and returns the supporting passages as citations.

Request

Headers

Header	Required	Notes
`X-API-Key`	yes
`X-External-User-Id`	yes (or `X-User-Id`)	Must own the course
`Content-Type`	yes	`application/json`

Path parameters

course_id string (UUID) required

The course to ground the answer in.

Body

question string required

Natural-language question. 1–2000 characters.

Returns

{
  "answer": "The Calvin cycle is the second stage of photosynthesis, where CO₂ is fixed into sugar using the ATP and NADPH from the light reactions…",
  "sources": [
    {
      "text": "In the Calvin cycle, CO₂ binds to RuBP, catalyzed by RuBisCO…",
      "score": 0.83
    },
    {
      "text": "ATP and NADPH from the light reactions power the reduction step…",
      "score": 0.78
    }
  ]
}

The sources array carries the raw chunks the model was conditioned on, with cosine-similarity scores. Use these for in-product citations or to detect low-confidence answers (score < 0.5 is a useful threshold).

Errors

404 — Course not found for this user.
422 — question empty or longer than 2000 characters.
429 — Rate limit exceeded.

curl -X POST "https://api.nuton.app/v2/courses/8fa640c0-22e6-436b-becd-bf2cfc86741a/ask" \ -H "X-API-Key: $NUTON_KEY" \ -H "X-External-User-Id: alice@example.com" \ -H "Content-Type: application/json" \ -d '{ "question": "Explain the Calvin cycle in simple terms." }'

{ "answer": "The Calvin cycle is the second stage of photosynthesis, where CO₂ is fixed into sugar using the ATP and NADPH from the light reactions…", "sources": [ { "text": "In the Calvin cycle, CO₂ binds to RuBP, catalyzed by RuBisCO…", "score": 0.83 }, { "text": "ATP and NADPH from the light reactions power the reduction step…", "score": 0.78 } ] }