Guides

Overview Getting Started Authentication Content Delivery Errors & Limits Production Readiness Examples API Reference

Reference

Status Questions Categories Category Suggestions

API docs navigation

Questions

post

/api/v1/questions

Deliver question content

Returns approved question content, including answers, in a single delivery response. Runtime behavior stays caller-owned.

Behavior Notes

Repeat avoidance is scoped to the API key by default; provide a stable `deliveryKey` to create a caller-defined repeat scope for a delivery scope, presentation run, or integration batch.
QuestionStock does not manage players, attempts, submissions, timers, scores, leaderboards, multiplayer rooms, or gameplay sessions.
Unseen questions are preferred. When unseen stock is exhausted, previously served questions are reused oldest-served first.
The endpoint never returns partial success. If the full `limit` cannot be satisfied, it returns `409 insufficient_stock`.
`image.url` is the supported render field for third-party apps. `image.key` is opaque diagnostics metadata and should not be used to derive public URLs.
If cheat resistance matters, keep `answer.*` server-side and reveal it only after the end user submits an answer.

Request Body

application/json

Responses

200Questions response

application/json

{
  "items": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "categoryId": "22222222-2222-4222-8222-222222222222",
      "difficulty": "medium",
      "questionType": "multiple_choice",
      "questionText": "Which planet is known as the Red Planet?",
      "options": [
        "Mercury",
        "Mars",
        "Venus",
        "Jupiter"
      ],
      "image": {
        "status": "ready",
        "key": "representative-images/questions/q-1/example.png",
        "url": "https://questionstock.com/images/representative/questions/q-1/example.png"
      },
      "createdAt": "2026-03-06T12:00:00.000Z",
      "answer": {
        "correctIndex": 1,
        "correctOption": "Mars",
        "explanation": "Mars appears red because of iron oxide on its surface."
      }
    }
  ],
  "query": {
    "limit": 1,
    "categoryIds": [
      "22222222-2222-4222-8222-222222222222"
    ],
    "difficulty": "mixed",
    "imageRule": "optional",
    "excludeQuestionIds": [
      "33333333-3333-4333-8333-333333333333"
    ],
    "deliveryKey": "presentation_run_001"
  },
  "owner": {
    "userId": "user_2abc123"
  }
}

400Invalid request body

application/json

{
  "error": "Bad Request",
  "issues": [
    {
      "path": [
        "deliveryKey"
      ],
      "message": "Invalid string: must match pattern /^[A-Za-z0-9._:-]+$/"
    }
  ]
}

401Unauthorized

application/json

{
  "error": "Unauthorized"
}

403Business plan required

application/json

{
  "error": "Forbidden",
  "message": "Business plan required for API access."
}

409Insufficient stock

application/json

{
  "error": "Conflict",
  "code": "insufficient_stock",
  "message": "Insufficient approved stock for the requested constraints.",
  "availableCount": 3,
  "requestedCount": 5,
  "constraints": {
    "categoryIds": [
      "22222222-2222-4222-8222-222222222222"
    ],
    "difficulty": "mixed",
    "imageRule": "required"
  }
}

429Rate limit or daily quota exceeded

application/json

Per-minute throttle

{
  "error": "Too Many Requests",
  "limit": 60
}

Daily quota exhausted

{
  "error": "Quota Exceeded",
  "limit": 10000
}

500Unexpected error

application/json

{
  "error": "Internal Server Error"
}

503Service unavailable

application/json

{
  "error": "Service Unavailable",
  "message": "Authentication dependencies are unavailable."
}

Request examples

cURL

bash

curl --request POST \
  --url 'https://questionstock.com/api/v1/questions' \
  --header 'Authorization: Bearer qsk_v1_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
  "limit": 1,
  "categoryIds": ["22222222-2222-4222-8222-222222222222"],
  "difficulty": "mixed",
  "imageRule": "optional",
  "excludeQuestionIds": ["33333333-3333-4333-8333-333333333333"],
  "deliveryKey": "presentation_run_001"
}'

JavaScript fetch

javascript

const response = await fetch("https://questionstock.com/api/v1/questions", {
  method: "POST",
  headers: {
    Authorization: "Bearer qsk_v1_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "limit": 1,
  "categoryIds": ["22222222-2222-4222-8222-222222222222"],
  "difficulty": "mixed",
  "imageRule": "optional",
  "excludeQuestionIds": ["33333333-3333-4333-8333-333333333333"],
  "deliveryKey": "presentation_run_001"
}),
});

if (!response.ok) {
  throw new Error("API error: " + response.status);
}

const data = await response.json();

{ "items": [ { "id": "11111111-1111-4111-8111-111111111111", "categoryId": "22222222-2222-4222-8222-222222222222", "difficulty": "medium", "questionType": "multiple_choice", "questionText": "Which planet is known as the Red Planet?", "options": [ "Mercury", "Mars", "Venus", "Jupiter" ], "image": { "status": "ready", "key": "representative-images/questions/q-1/example.png", "url": "https://questionstock.com/images/representative/questions/q-1/example.png" }, "createdAt": "2026-03-06T12:00:00.000Z", "answer": { "correctIndex": 1, "correctOption": "Mars", "explanation": "Mars appears red because of iron oxide on its surface." } } ], "query": { "limit": 1, "categoryIds": [ "22222222-2222-4222-8222-222222222222" ], "difficulty": "mixed", "imageRule": "optional", "excludeQuestionIds": [ "33333333-3333-4333-8333-333333333333" ], "deliveryKey": "presentation_run_001" }, "owner": { "userId": "user_2abc123" } }

{ "error": "Conflict", "code": "insufficient_stock", "message": "Insufficient approved stock for the requested constraints.", "availableCount": 3, "requestedCount": 5, "constraints": { "categoryIds": [ "22222222-2222-4222-8222-222222222222" ], "difficulty": "mixed", "imageRule": "required" } }

Request examples

cURL

bash

curl --request POST \
  --url 'https://questionstock.com/api/v1/questions' \
  --header 'Authorization: Bearer qsk_v1_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
  "limit": 1,
  "categoryIds": ["22222222-2222-4222-8222-222222222222"],
  "difficulty": "mixed",
  "imageRule": "optional",
  "excludeQuestionIds": ["33333333-3333-4333-8333-333333333333"],
  "deliveryKey": "presentation_run_001"
}'

JavaScript fetch

javascript

const response = await fetch("https://questionstock.com/api/v1/questions", {
  method: "POST",
  headers: {
    Authorization: "Bearer qsk_v1_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "limit": 1,
  "categoryIds": ["22222222-2222-4222-8222-222222222222"],
  "difficulty": "mixed",
  "imageRule": "optional",
  "excludeQuestionIds": ["33333333-3333-4333-8333-333333333333"],
  "deliveryKey": "presentation_run_001"
}),
});

if (!response.ok) {
  throw new Error("API error: " + response.status);
}

const data = await response.json();