Generate a worksheet with the API

The Worksheet Builder writes practice questions, answers, and explanations for a class, subject, and topic. It takes four API calls, and a teacher can review the draft after each one. This guide is for developers. For a non-technical overview, see Worksheet Builder features.

Step	You call	You get back	Teacher can
1	Start a worksheet	Topics, concepts, and learning objectives	Add or remove topics
2	Configure questions	A plan for every question	Change types, difficulty, or Bloom’s levels
3	Generate questions	Questions and an answer key	Use the worksheet
4	Generate explanations (optional)	An explanation for every question

Each call starts a background job. Wait until the job’s status is Completed before the next call. The wait_for helper below does this for you.

Set up

You need an access token. If you don’t have one, follow the Quickstart.

import json
import time

import requests

BASE_URL = "https://api.crazygoldfish.com"
HEADERS = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}


def wait_for(path):
    """Check the job every 5 seconds until it's Completed."""
    for _ in range(120):  # Give up after 10 minutes
        response = requests.get(BASE_URL + path, headers=HEADERS)
        body = response.json()
        if response.status_code == 200:
            if body["data"]["status"] == "Completed":
                return body["data"]
        elif response.status_code not in (400, 404):
            response.raise_for_status()
        elif body["detail"][0].get("status") == "Failed":
            raise RuntimeError(body["detail"][0]["msg"])
        time.sleep(5)
    raise TimeoutError(f"{path} took longer than 10 minutes")

const BASE_URL = "https://api.crazygoldfish.com";
const HEADERS = { Authorization: "Bearer YOUR_ACCESS_TOKEN" };

// Check the job every 5 seconds until it's Completed
async function waitFor(path) {
  for (let i = 0; i < 120; i++) { // Give up after 10 minutes
    const response = await fetch(BASE_URL + path, { headers: HEADERS });
    const body = await response.json();
    if (response.status === 200) {
      if (body.data.status === "Completed") return body.data;
    } else if (![400, 404].includes(response.status)) {
      throw new Error(JSON.stringify(body));
    } else if (body.detail[0].status === "Failed") {
      throw new Error(body.detail[0].msg);
    }
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
  throw new Error(`${path} took longer than 10 minutes`);
}

While a job is starting, the API can briefly return 404, and explanations return 400 until they’re ready. wait_for keeps checking in both cases and stops only if the job failed.

Step 1: Start the worksheet

Send the board, grade, and subject, a topic, and how many questions you want. The three distributions are JSON strings.

response = requests.post(
    BASE_URL + "/worksheet/v1/metadata",
    headers=HEADERS,
    data={
        "board": BOARD_ID,
        "grade": GRADE_ID,
        "subject": SUBJECT_ID,
        "topic": "Magnetic Effects of Electric Current",
        "number_of_questions": 5,
        "question_distribution": json.dumps(
            {"mcq_single_answer": 3, "short_answer": 2}
        ),
        "difficulty_level_distribution": json.dumps(
            {"easy": 40, "medium": 40, "hard": 20}
        ),
        "bloom_taxonomy_distribution": json.dumps(
            {"remember": 40, "understand": 40, "apply": 20}
        ),
    },
)
response.raise_for_status()
worksheet_id = response.json()["detail"][0]["id"]

metadata = wait_for(f"/worksheet/v1/metadata/{worksheet_id}")

const form = new FormData();
form.append("board", BOARD_ID);
form.append("grade", GRADE_ID);
form.append("subject", SUBJECT_ID);
form.append("topic", "Magnetic Effects of Electric Current");
form.append("number_of_questions", "5");
form.append("question_distribution",
  JSON.stringify({ mcq_single_answer: 3, short_answer: 2 }));
form.append("difficulty_level_distribution",
  JSON.stringify({ easy: 40, medium: 40, hard: 20 }));
form.append("bloom_taxonomy_distribution",
  JSON.stringify({ remember: 40, understand: 40, apply: 20 }));

const response = await fetch(BASE_URL + "/worksheet/v1/metadata", {
  method: "POST",
  headers: HEADERS,
  body: form,
});
if (!response.ok) throw new Error(await response.text());
const worksheetId = (await response.json()).detail[0].id;

const metadata = await waitFor(`/worksheet/v1/metadata/${worksheetId}`);

Get BOARD_ID, GRADE_ID, and SUBJECT_ID from List boards, List grades, and List subjects. They don’t change, so you can store them.

What you get back

{
  "id": "152764ca-1685-427c-aba7-4b92dcc0d60f",
  "status": "Completed",
  "subject_matter": {
    "topics_to_be_covered": {
      "topic": {
        "ai_recommendations": [
          "Magnetic field and field lines around a bar magnet",
          "Right-hand thumb rule"
        ],
        "additional_recommendations": []
      }
    },
    "key_concepts_and_subconcepts": { "concepts": { "...": "..." } },
    "prerequisite_knowledge": { "prerequisite": { "...": "..." } }
  },
  "learning_standards": {
    "learning_outcomes": { "outcomes": { "...": "..." } },
    "smart_learning_objectives": { "objects": { "...": "..." } }
  }
}

A teacher can remove items, or add their own to additional_recommendations.

Step 2: Configure the questions

Send subject_matter and learning_standards back, with any edits. You get a plan for every question.

response = requests.post(
    BASE_URL + f"/worksheet/v1/question-config/{worksheet_id}",
    headers=HEADERS,
    json={
        "subject_matter": metadata["subject_matter"],
        "learning_standards": metadata["learning_standards"],
    },
)
response.raise_for_status()

config = wait_for(f"/worksheet/v1/question-config/{worksheet_id}")
plan = config["question_configuration"]

const configResponse = await fetch(
  `${BASE_URL}/worksheet/v1/question-config/${worksheetId}`,
  {
    method: "POST",
    headers: { ...HEADERS, "Content-Type": "application/json" },
    body: JSON.stringify({
      subject_matter: metadata.subject_matter,
      learning_standards: metadata.learning_standards,
    }),
  },
);
if (!configResponse.ok) throw new Error(await configResponse.text());

const config = await waitFor(`/worksheet/v1/question-config/${worksheetId}`);
const plan = config.question_configuration;

What you get back

{
  "question_type_summary": [
    { "question_type": "mcq_single_answer", "count": 3 },
    { "question_type": "short_answer", "count": 2 }
  ],
  "bloom_summary": [
    { "bloom": "remember", "question_count": 2 },
    { "bloom": "understand", "question_count": 2 },
    { "bloom": "apply", "question_count": 1 }
  ],
  "difficulty_summary": [
    { "difficulty": "easy", "question_count": 2 },
    { "difficulty": "medium", "question_count": 2 },
    { "difficulty": "hard", "question_count": 1 }
  ],
  "question_summary": [
    {
      "question_type": "mcq_single_answer",
      "learning_objectives": "Recall the properties of magnetic field lines",
      "bloom": "remember",
      "difficulty": "easy",
      "question_count": 2
    }
  ]
}

question_summary is trimmed here. In a real response, its counts add up to the number of questions.

Step 3: Generate the questions

Send the plan back, with any edits. You get the questions and the answer key.

If you edit the plan, the counts in each of the four lists must still add up to number_of_questions.

response = requests.post(
    BASE_URL + f"/worksheet/v1/generate-worksheet/{worksheet_id}",
    headers=HEADERS,
    json=plan,
)
response.raise_for_status()

worksheet = wait_for(f"/worksheet/v1/generate-worksheet/{worksheet_id}")
questions = worksheet["questions"]

const generateResponse = await fetch(
  `${BASE_URL}/worksheet/v1/generate-worksheet/${worksheetId}`,
  {
    method: "POST",
    headers: { ...HEADERS, "Content-Type": "application/json" },
    body: JSON.stringify(plan),
  },
);
if (!generateResponse.ok) throw new Error(await generateResponse.text());

const worksheet = await waitFor(`/worksheet/v1/generate-worksheet/${worksheetId}`);
const questions = worksheet.questions;

What you get back

Questions are grouped by type. Only multiple-choice questions have options.

{
  "mcq_single_answer": [
    {
      "question": "Which statement about magnetic field lines is correct?",
      "options": [
        "A. They cross each other near the poles",
        "B. They start at the south pole outside the magnet",
        "C. They are closer together where the field is stronger",
        "D. They are straight lines around a bar magnet"
      ],
      "answer": "C",
      "tags": { "bloom": "Remember", "difficulty": "Easy" }
    }
  ],
  "short_answer": [
    {
      "question": "Why do two magnetic field lines never intersect?",
      "answer": "A compass needle can't point in two directions at once.",
      "tags": { "bloom": "Understand", "difficulty": "Medium" }
    }
  ]
}

Step 4: Add explanations (optional)

Add a step-by-step explanation, key concepts, and common mistakes to every question.

requests.post(
    BASE_URL + f"/worksheet/v1/generate-explanations/{worksheet_id}",
    headers=HEADERS,
).raise_for_status()

explained = wait_for(f"/worksheet/v1/generate-explanations/{worksheet_id}")

const explainResponse = await fetch(
  `${BASE_URL}/worksheet/v1/generate-explanations/${worksheetId}`,
  { method: "POST", headers: HEADERS },
);
if (!explainResponse.ok) throw new Error(await explainResponse.text());

const explained = await waitFor(`/worksheet/v1/generate-explanations/${worksheetId}`);

Each question in explained["questions"] now has an explanations list.

Good to know

Limits

Limit	Value
Questions per worksheet	Up to 10
Source material	One of `topic`, `documents` (up to 4 `.jpg` or `.png` images, 5 MB each), or `audio` (one `.mp3`, 5 MB)
Distributions	Question counts add up to `number_of_questions`. Difficulty and Bloom’s percentages add up to 100.
Starting worksheets	Daily limit per account. Rejected requests count too.
Each step	Runs once per worksheet. You can retry a step only if it failed.

Use webhooks instead of polling

Step	Event
1. Start a worksheet	`worksheet_initialize_metadata`
2. Configure questions	`worksheet_question_configuration`
3. Generate questions	`worksheet_generation`
4. Generate explanations	`worksheet_explanation_generation`

Troubleshooting

Error	Fix
`Total questions in distribution must equal number_of_questions.`	Make the question counts add up to `number_of_questions`
`Total mismatch: total_questions are 5 but ...`	Fix the list named in the message so it adds up
`Only one of topic, documents, or audio should be provided.`	Send only one source
`... already In Progress.` or `already Completed.`	The step already ran. Get its result instead.
Job failed with `No content found`	There’s no textbook content for that board, grade, and subject. Send `documents` instead of `topic`.
`429 Daily rate limit exceeded`	Try again after 00:01 server time
Still `In Progress` after 10 minutes	Start a new worksheet and contact us with the worksheet ID

Worksheet API reference

Every field, response, and error.

List worksheets

Show a teacher’s worksheet history.

Get started

Guides

Exam Evaluation

Assignment Evaluation

Rubrics

Action Plans

Lesson Plan Builder

Worksheet Builder

ClassTrack

Metadata

Webhooks

Generate a worksheet with the API

Set up

Step 1: Start the worksheet

Step 2: Configure the questions

Step 3: Generate the questions

Step 4: Add explanations (optional)

Good to know

Worksheet API reference

List worksheets

​Set up

​Step 1: Start the worksheet

​Step 2: Configure the questions

​Step 3: Generate the questions

​Step 4: Add explanations (optional)

​Good to know

​Related

Worksheet API reference

List worksheets

Set up

Step 1: Start the worksheet

Step 2: Configure the questions

Step 3: Generate the questions

Step 4: Add explanations (optional)

Good to know

Related