POST - Generate Worksheet Metadata

Generates metadata for a worksheet based on provided inputs such as board, grade, subject, section, number of questions, and optional resources (documents or audio). The request also accepts distributions for question types, difficulty levels, and Bloom’s taxonomy levels.

How to Use:

Call POST /worksheet/v1/metadata with required fields (board, grade, subject, number_of_questions, and distributions) and optionally provide topic, section, documents, or audio.
On success, the request is queued for background processing to generate worksheet metadata. You’ll receive a unique id and confirmation message in the response.
If inputs are invalid (e.g., number of questions exceeds allowed limits or malformed JSON distributions), a 400 error is returned.
If processing starts successfully, a 200 response is returned with the request ID.
If an unexpected error occurs during submission, a 500 error is returned.

Question Type Distribution:

   {
       "mcq_single_answer": 2,
       "mcq_multiple_answer": 3,
       "true_false": 1,
       "fill_in_the_blanks": 0,
       "very_short_answer": 1,
       "short_answer": 1,
       "long_answer": 2,
       "match_the_column": 0
   }

The sum of question_type_distribution must equal number_of_questions.

Difficulty Level Distribution (%)

    {
        "easy": 30,
        "medium": 50,
        "hard": 20
    }

Bloom’s Taxonomy Distribution (%)

    {
        "remember": 30,
        "understand": 30,
        "apply": 30,
        "analyze": 10,
        "evaluate": 0,
        "create": 0
    }

The sum of difficulty_level_distribution and bloom_taxonomy_distribution must each equal 100.

POST

worksheet

metadata

Generate Worksheet Metadata

curl --request POST \
  --url https://api-staging.crazygoldfish.com/worksheet/v1/metadata \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form board=087c80b0-ac25-40ee-8657-28b694882ba8 \
  --form grade=65955148-e106-461b-a9a6-e0c3294f6734 \
  --form subject=5dcc9bab-e2ac-4c65-a3d0-e272ac4bc5ea \
  --form number_of_questions=10 \
  --form 'question_distribution={"mcq_single_answer": 2, "mcq_multiple_answer": 3, "true_false": 1, "fill_in_the_blanks": 0, "very_short_answer": 1, "short_answer": 1, "long_answer": 2, "match_the_column": 0}' \
  --form 'difficulty_level_distribution={"easy": 30, "medium": 50, "hard": 20}' \
  --form 'bloom_taxonomy_distribution={"remember": 30, "understand": 30, "apply": 30, "analyze": 10, "evaluate": 0, "create": 0}' \
  --form section=A \
  --form topic=Magnet \
  --form 'documents=<string>' \
  --form 'audio=<string>' \
  --form 'meta_data={"teacher_id": 199}' \
  --form documents.0='@example-file' \
  --form documents.1='@example-file' \
  --form audio.0='@example-file' \
  --form audio.1='@example-file'

{
  "detail": [
    {
      "id": "84dad129-76dc-44b6-84ad-4f55fd451891",
      "msg": "Worksheet metadata processing started successfully."
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

multipart/form-data

board

string<uuid>

required

Example:

"087c80b0-ac25-40ee-8657-28b694882ba8"

grade

string<uuid>

required

Example:

"65955148-e106-461b-a9a6-e0c3294f6734"

subject

string<uuid>

required

Example:

"5dcc9bab-e2ac-4c65-a3d0-e272ac4bc5ea"

number_of_questions

integer

required

Example:

10

question_distribution

string

required

JSON string representing question type distribution

Example:

"{\"mcq_single_answer\": 2, \"mcq_multiple_answer\": 3, \"true_false\": 1, \"fill_in_the_blanks\": 0, \"very_short_answer\": 1, \"short_answer\": 1, \"long_answer\": 2, \"match_the_column\": 0}"

difficulty_level_distribution

string

required

JSON string representing difficulty distribution

Example:

"{\"easy\": 30, \"medium\": 50, \"hard\": 20}"

bloom_taxonomy_distribution

string

required

JSON string representing Bloom taxonomy distribution

Example:

"{\"remember\": 30, \"understand\": 30, \"apply\": 30, \"analyze\": 10, \"evaluate\": 0, \"create\": 0}"

section

string | null

Example:

"A"

topic

string | null

Example:

"Magnet"

documents

file | null

Array of document files

audio

file | null

Audio file for question generation

meta_data

string

JSON string representing the metadata of the worksheet

Example:

"{\"teacher_id\": 199}"

Response

Worksheet metadata processing started successfully.

string

Unique identifier for the worksheet metadata request.

Example:

"84dad129-76dc-44b6-84ad-4f55fd451891"

msg

string

Confirmation msg indicating successful processing start.

Example:

"Worksheet metadata processing started successfully."

GET - Worksheet Metadata by IDRetrieves metadata for a specific worksheet by its ID. The response includes board, grade, subject, status, number of questions, topic, subject matter (topics, prerequisites, concepts), and learning standards. **How to Use:** 1. Call `GET /worksheet/v1/metadata/{work_sheet_id}` with the worksheet ID. 2. On success, you receive full worksheet metadata in the response. 3. If the worksheet is not found, a `404` error is returned.

Generate Worksheet Metadata

curl --request POST \
  --url https://api-staging.crazygoldfish.com/worksheet/v1/metadata \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form board=087c80b0-ac25-40ee-8657-28b694882ba8 \
  --form grade=65955148-e106-461b-a9a6-e0c3294f6734 \
  --form subject=5dcc9bab-e2ac-4c65-a3d0-e272ac4bc5ea \
  --form number_of_questions=10 \
  --form 'question_distribution={"mcq_single_answer": 2, "mcq_multiple_answer": 3, "true_false": 1, "fill_in_the_blanks": 0, "very_short_answer": 1, "short_answer": 1, "long_answer": 2, "match_the_column": 0}' \
  --form 'difficulty_level_distribution={"easy": 30, "medium": 50, "hard": 20}' \
  --form 'bloom_taxonomy_distribution={"remember": 30, "understand": 30, "apply": 30, "analyze": 10, "evaluate": 0, "create": 0}' \
  --form section=A \
  --form topic=Magnet \
  --form 'documents=<string>' \
  --form 'audio=<string>' \
  --form 'meta_data={"teacher_id": 199}' \
  --form documents.0='@example-file' \
  --form documents.1='@example-file' \
  --form audio.0='@example-file' \
  --form audio.1='@example-file'

{
  "detail": [
    {
      "id": "84dad129-76dc-44b6-84ad-4f55fd451891",
      "msg": "Worksheet metadata processing started successfully."
    }
  ]
}

Documentation Index

Authorizations

Body

Response