> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crazygoldfish.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:**
1. Call `POST /worksheet/v1/metadata` with required fields (`board`, `grade`, `subject`, `number_of_questions`, and distributions) and optionally provide `topic`, `section`, `documents`, or `audio`.
2. 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.
3. If inputs are invalid (e.g., number of questions exceeds allowed limits or malformed JSON distributions), a `400` error is returned.
4. If processing starts successfully, a `200` response is returned with the request ID.
5. 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.
## OpenAPI
````yaml POST /worksheet/v1/metadata
openapi: 3.0.1
info:
title: Evaluation Report API
description: An API for retrieving evaluation reports.
version: 1.0.0
servers:
- url: https://api-staging.crazygoldfish.com
description: SandBox endpoint
- url: https://api.crazygoldfish.com
description: Prod End Point
security: []
paths:
/worksheet/v1/metadata:
post:
summary: Generate Worksheet Metadata
description: >-
Generates worksheet metadata based on inputs like board, grade, subject,
number of questions, and optional distributions (question type,
difficulty, Bloom's taxonomy). Documents and audio files can also be
uploaded.
operationId: generateWorksheetMetadata
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
board:
type: string
format: uuid
example: 087c80b0-ac25-40ee-8657-28b694882ba8
grade:
type: string
format: uuid
example: 65955148-e106-461b-a9a6-e0c3294f6734
subject:
type: string
format: uuid
example: 5dcc9bab-e2ac-4c65-a3d0-e272ac4bc5ea
section:
type: string
nullable: true
example: A
topic:
type: string
nullable: true
example: Magnet
number_of_questions:
type: integer
example: 10
question_distribution:
type: string
description: 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:
type: string
description: JSON string representing difficulty distribution
example: '{"easy": 30, "medium": 50, "hard": 20}'
bloom_taxonomy_distribution:
type: string
description: JSON string representing Bloom taxonomy distribution
example: >-
{"remember": 30, "understand": 30, "apply": 30, "analyze":
10, "evaluate": 0, "create": 0}
documents:
type: string
description: Array of document files
format: binary
nullable: true
audio:
type: string
format: binary
description: Audio file for question generation
nullable: true
meta_data:
type: string
description: JSON string representing the metadata of the worksheet
example: '{"teacher_id": 199}'
required:
- board
- grade
- subject
- number_of_questions
- question_distribution
- difficulty_level_distribution
- bloom_taxonomy_distribution
responses:
'200':
description: Worksheet metadata processing started successfully.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Unique identifier for the worksheet metadata request.
example: 84dad129-76dc-44b6-84ad-4f55fd451891
msg:
type: string
description: Confirmation msg indicating successful processing start.
example: Worksheet metadata processing started successfully.
example:
detail:
- id: 84dad129-76dc-44b6-84ad-4f55fd451891
msg: Worksheet metadata processing started successfully.
'400':
description: Bad request due to invalid inputs or distribution mismatch.
content:
application/json:
schema:
type: object
properties:
detail:
type: array
items:
type: object
properties:
msg:
type: string
example: >-
Total questions in distribution must equal
number_of_questions.
example:
detail:
- msg: >-
Total questions in distribution must equal
number_of_questions.
'500':
description: Internal server error due to processing or JSON parsing failure.
content:
application/json:
schema:
type: object
properties:
detail:
type: array
items:
type: object
properties:
msg:
type: string
example: Invalid JSON format of difficulty_level_distribution
example:
detail:
- msg: Invalid JSON format of difficulty_level_distribution
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````