Content Delivery

POST /api/v1/questions is a content-delivery endpoint. It returns question payloads, answers, and image metadata, but it does not manage players, attempts, submissions, timers, scores, leaderboards, multiplayer rooms, or gameplay sessions for you.

Open endpoint reference Production guide

Runtime ownership

Runtime logic is caller-owned. QuestionStock returns the answer data you need for evaluation and reveal, but it does not create score records, attempts, or session summaries for you.

Use answer.correctIndex against options for server-authoritative scoring.
Use answer.correctOption for display/review convenience.
Keep answer.* on a trusted backend if cheat resistance matters.

Server-side evaluation sketch

json

{
  "selectedIndex": 1,
  "isCorrect": selectedIndex === question.answer.correctIndex,
  "correctAnswerLabel": question.answer.correctOption
}

Answer exposure guidance

If you are building a trusted backend, fetch full question payloads on the server and strip answer.* before sending the question to untrusted clients.
If you control both user flow and answer reveal, keep the QuestionStock API key server-side and reveal the explanation only after the end user submits an answer.
If cheat resistance is not a concern, you can use the full response directly inside your own backend-rendered flows.

Repeat behavior

Without a deliveryKey, repeat avoidance is scoped to the API key.
With a stable deliveryKey, repeat avoidance is scoped to the caller-defined delivery scope, presentation run, or integration batch.
New questions are preferred first. If unseen stock runs out, the API falls back to previously served questions in oldest-served-first order.
The API never returns partial success. If the full limit cannot be satisfied, it returns 409 insufficient_stock.
Use excludeQuestionIds when you already track served question IDs yourself. The request cap is 500 excluded IDs.

Image handling

Use image.url as the only supported render field for third-party apps.
image.url is non-null only when image.status is ready.
image.key is opaque metadata for diagnostics and support workflows. Do not derive public URLs from it.
Treat pending, failed, and none as non-renderable states in client UI.

Renderable image payload

json

{
  "image": {
    "status": "ready",
    "key": "representative-images/questions/q-1/example.png",
    "url": "https://questionstock.com/images/representative/questions/q-1/example.png"
  }
}

Runtime ownership

Runtime logic is caller-owned. QuestionStock returns the answer data you need for evaluation and reveal, but it does not create score records, attempts, or session summaries for you.

Use answer.correctIndex against options for server-authoritative scoring.
Use answer.correctOption for display/review convenience.
Keep answer.* on a trusted backend if cheat resistance matters.

Server-side evaluation sketch

json

{
  "selectedIndex": 1,
  "isCorrect": selectedIndex === question.answer.correctIndex,
  "correctAnswerLabel": question.answer.correctOption
}

Answer exposure guidance

If you are building a trusted backend, fetch full question payloads on the server and strip answer.* before sending the question to untrusted clients.

If you control both user flow and answer reveal, keep the QuestionStock API key server-side and reveal the explanation only after the end user submits an answer.

If cheat resistance is not a concern, you can use the full response directly inside your own backend-rendered flows.

Repeat behavior

Without a deliveryKey, repeat avoidance is scoped to the API key.
With a stable deliveryKey, repeat avoidance is scoped to the caller-defined delivery scope, presentation run, or integration batch.
New questions are preferred first. If unseen stock runs out, the API falls back to previously served questions in oldest-served-first order.
The API never returns partial success. If the full limit cannot be satisfied, it returns 409 insufficient_stock.
Use excludeQuestionIds when you already track served question IDs yourself. The request cap is 500 excluded IDs.

Image handling

Use image.url as the only supported render field for third-party apps.
image.url is non-null only when image.status is ready.
image.key is opaque metadata for diagnostics and support workflows. Do not derive public URLs from it.
Treat pending, failed, and none as non-renderable states in client UI.

Renderable image payload

json

{
  "image": {
    "status": "ready",
    "key": "representative-images/questions/q-1/example.png",
    "url": "https://questionstock.com/images/representative/questions/q-1/example.png"
  }
}