API Reference

curl https://api.makequestions.ai/generate-questions \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
        "context": "Your text here...",
        "question_config": {
          "type_counts": {
            "true_false": 3,
            "multiple_choice": 2,
            "short_answer": 1,
            "fill-in-the-blank": 1,
            "reorder": 1
          },
          "difficulty": "medium"
        }
      }'

{
  "context": "Photosynthesis is the process by which plants convert sunlight into energy.",
  "question_config": {
    "type_counts": {
      "multiple_choice": 2,
      "true_false": 1
    },
    "difficulty": "medium"
  },
  "input": "Use concise, exam-style wording.",
  "attachments": [
    {
      "url": "https://cdn.example.com/photosynthesis-notes.pdf",
      "mime_type": "application/pdf",
      "name": "photosynthesis-notes.pdf"
    }
  ],
  "reasoning": true,
  "streaming": false
}

{
  "success": true,
  "response_id": "resp_abc123",
  "total_questions": 3,
  "questions": [
    {
      "type": "multiple_choice",
      "difficulty": "medium",
      "question": "What do plants convert into energy?",
      "choices": [
        { "key": "c1", "label": "Sunlight" },
        { "key": "c2", "label": "Water" },
        { "key": "c3", "label": "Soil" },
        { "key": "c4", "label": "Air" }
      ],
      "answer": { "value": "c1" },
      "id": "8b2f0a5c-6e5e-4a1b-9b5e-9a9f1c4e6a7d",
      "created_at": "2026-04-22T17:00:00.000Z"
    },
    {
      "type": "multiple_choice",
      "difficulty": "medium",
      "question": "Which organelle is the main site of photosynthesis?",
      "choices": [
        { "key": "c1", "label": "Chloroplast" },
        { "key": "c2", "label": "Mitochondrion" },
        { "key": "c3", "label": "Nucleus" },
        { "key": "c4", "label": "Ribosome" }
      ],
      "answer": { "value": "c1" },
      "id": "c4d8e1f2-3a4b-5c6d-7e8f-901234abcdef",
      "created_at": "2026-04-22T17:00:01.000Z"
    },
    {
      "type": "true_false",
      "difficulty": "medium",
      "question": "Photosynthesis releases oxygen as a byproduct.",
      "choices": [
        { "key": "true", "label": "True" },
        { "key": "false", "label": "False" }
      ],
      "answer": { "value": "true" },
      "id": "d5e9f0a3-4b5c-6d7e-8f90-123456789abc",
      "created_at": "2026-04-22T17:00:02.000Z"
    }
  ],
  "validation": {
    "requested_counts": { "multiple_choice": 2, "true_false": 1 },
    "actual_counts": { "multiple_choice": 2, "true_false": 1 },
    "is_exact_match": true
  }
}

{
  "response_id": "resp_abc123",
  "request_type": "more-questions",
  "question_config": {
    "type_counts": { "true_false": 2 },
    "difficulty": "easy"
  },
  "input": "Focus on practical examples.",
  "reasoning": true,
  "streaming": false
}

event: question
data: {"index": 1, "question": {"type": "multiple_choice", ...}}

event: question
data: {"index": 2, "question": {"type": "true_false", ...}}

event: done
data: {"success": true, "response_id": "resp_abc123", "total_questions": 2}

{
  "type": "multiple_choice",
  "difficulty": "easy",
  "question": "What is the capital of France?",
  "choices": [
    { "key": "c1", "label": "Paris" },
    { "key": "c2", "label": "London" },
    { "key": "c3", "label": "Berlin" },
    { "key": "c4", "label": "Madrid" }
  ],
  "answer": { "value": "c1" },
  "id": "8b2f0a5c-6e5e-4a1b-9b5e-9a9f1c4e6a7d",
  "created_at": "2026-04-22T17:00:00.000Z"
}

const response = await fetch("https://api.makequestions.ai/generate-questions", {
  method: "POST",
  headers: {
    "X-API-Key": "your-api-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    context: "Your text...",
    question_config: {
      type_counts: { multiple_choice: 3, true_false: 2 },
      difficulty: null
    },
    streaming: true
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const text = decoder.decode(value);
  // Parse SSE events and handle questions
  console.log(text);
}

// lib/api.ts
// Call this from the server only (a Route Handler or Server Action). Your API
// key must never reach the browser — do NOT put it in a NEXT_PUBLIC_ variable.
const API_URL = "https://api.makequestions.ai";

type ConcreteQuestionType =
  | "multiple_choice" | "true_false" | "short_answer" | "exact_answer"
  | "reorder" | "code-output" | "matching" | "fill-in-the-blank";

type QuestionConfig = {
  // Required, non-empty. Positive int = exact count; null = model decides
  // quantity with a guaranteed minimum of 1 of that type.
  type_counts: Partial<Record<ConcreteQuestionType, number | null>>;
  difficulty?: "easy" | "medium" | "hard" | null;
};

type Attachment = {
  url: string;       // public HTTPS URL
  mime_type: string; // e.g. "application/pdf", "image/png"
  name?: string;     // optional original filename
};

export async function generateQuestions(
  context: string,
  questionConfig: QuestionConfig,
  options?: {
    input?: string | null;
    attachments?: Attachment[] | null; // preferred for files (images + documents)
    imageUrls?: string[] | null;       // legacy; prefer attachments
    reasoning?: boolean;
  }
) {
  const response = await fetch(`${API_URL}/generate-questions`, {
    method: "POST",
    headers: {
      "X-API-Key": process.env.MAKEQUESTIONS_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      context,
      question_config: questionConfig,
      input: options?.input ?? null,
      attachments: options?.attachments ?? null,
      image_urls: options?.imageUrls ?? null,
      reasoning: options?.reasoning ?? true, // default is reasoning mode; pass false for instant
    }),
  });

  if (!response.ok) {
    throw new Error("Failed to generate questions");
  }

  return response.json();
}