> ## 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

> Initiates the worksheet question generation process for a given worksheet after validation of its configuration.  
This step ensures that the worksheet is generated based on the finalized **question configuration** (Bloom’s taxonomy, difficulty levels, and question types).  

**How to Use:**
 1. Call `POST /worksheet/v1/generate-worksheet/{work_sheet_id}` with a valid worksheet ID.
 2. Provide the complete **question configuration** in the request body, including:
    - `question_summary`
    - `bloom_summary`
    - `difficulty_summary`
    - `question_type_summary`
 3. All counts must add up to the worksheet’s total `number_of_questions`.
 4. If validation passes, the generation job is queued and you receive confirmation.

**Path Parameters:**
- `work_sheet_id` (UUID, required): The unique ID of the worksheet.


## When to use this endpoint

Call this endpoint after you have:

1. Created a worksheet shell and initialized its metadata.
2. Finalized the **question configuration** using the configuration APIs.
3. Validated that the totals across `question_summary`, `bloom_summary`, `difficulty_summary`, and `question_type_summary` match `number_of_questions`.

Typical scenarios:

* LMS or homework platforms that queue **auto‑generated practice sheets** once teachers approve the configuration.
* Admin dashboards that generate **board‑aligned worksheets** in bulk for multiple classes.
* Programmatic integrations that run **nightly worksheet jobs** based on student performance data.

## Related endpoints

* [POST - Initialize Worksheet Metadata](/api-reference/endpoint/worksheet/v1-worksheet-meta-data-post)
* [POST - Worksheet Question Configuration](/api-reference/endpoint/worksheet/v1-worksheet-question-config-post)
* [GET - Worksheet Generation Status](/api-reference/endpoint/worksheet/v1-worksheet-generation-get)


## OpenAPI

````yaml POST /worksheet/v1/generate-worksheet/{work_sheet_id}
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/generate-worksheet/{work_sheet_id}:
    post:
      summary: Generate Worksheet
      description: >-
        Initiates the worksheet generation process for a given worksheet.
        Validates that `question_summary`, `bloom_summary`,
        `difficulty_summary`, and `question_type_summary` totals match the
        worksheet’s number of questions before queueing generation.
      operationId: generateWorksheet
      parameters:
        - name: work_sheet_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the worksheet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateWorksheetRequest'
            example:
              question_type_summary:
                - question_type: mcq_single_answer
                  count: 2
                - question_type: mcq_multiple_answer
                  count: 3
                - question_type: true_false
                  count: 1
                - question_type: very_short_answer
                  count: 1
                - question_type: short_answer
                  count: 1
                - question_type: long_answer
                  count: 2
              bloom_summary:
                - bloom: remember
                  question_count: 3
                - bloom: understand
                  question_count: 3
                - bloom: apply
                  question_count: 3
                - bloom: analyze
                  question_count: 1
              difficulty_summary:
                - difficulty: easy
                  question_count: 3
                - difficulty: medium
                  question_count: 5
                - difficulty: hard
                  question_count: 2
              question_summary:
                - question_type: mcq_single_answer
                  learning_objectives: Students will explain ...
                  bloom: understand
                  difficulty: easy
                  question_count: 1
                - question_type: long_answer
                  learning_objectives: Students will differentiate materials...
                  bloom: remember
                  difficulty: hard
                  question_count: 1
      responses:
        '200':
          description: Worksheet generation initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: 152764ca-1685-427c-aba7-4b92dcc0d60f
                        msg:
                          type: string
                          example: Worksheet generation initiated successfully.
              example:
                detail:
                  - id: 152764ca-1685-427c-aba7-4b92dcc0d60f
                    msg: Worksheet generation initiated successfully.
        '400':
          description: >-
            Bad request. Worksheet not finalized or generation already in
            progress.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: array
                    items:
                      type: object
                      properties:
                        msg:
                          type: string
                          example: Worksheet question configuration is not finalized!
              example:
                detail:
                  - msg: Worksheet question configuration is not finalized!
        '404':
          description: Worksheet not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: array
                    items:
                      type: object
                      properties:
                        msg:
                          type: string
                          example: Worksheet not found.
              example:
                detail:
                  - msg: Worksheet not found.
        '422':
          description: >-
            Validation error - totals mismatch between summaries and
            number_of_questions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: array
                    items:
                      type: object
                      properties:
                        msg:
                          type: string
                          example: >-
                            Total mismatch: total_questions are 10 but
                            question_summary expanded total=8
              example:
                detail:
                  - msg: >-
                      Total mismatch: total_questions are 10 but
                      question_summary expanded total=8
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: array
                    items:
                      type: object
                      properties:
                        msg:
                          type: string
                          example: Unexpected server error.
              example:
                detail:
                  - msg: Unexpected server error.
      security:
        - bearerAuth: []
components:
  schemas:
    GenerateWorksheetRequest:
      type: object
      properties:
        question_type_summary:
          type: array
          description: Summary of question types and their counts.
          items:
            type: object
            properties:
              question_type:
                type: string
                description: Type of question (e.g., mcq_single_answer, true_false, etc.)
              count:
                type: integer
                description: Number of questions of this type.
        bloom_summary:
          type: array
          items:
            type: object
            properties:
              bloom:
                type: string
                description: >-
                  Bloom's taxonomy level (e.g., Remember, Understand, Apply,
                  etc.)
              question_count:
                type: integer
                description: Number of questions at this Bloom's level.
        difficulty_summary:
          type: array
          items:
            type: object
            properties:
              difficulty:
                type: string
                description: Difficulty level (e.g., easy, medium, hard)
              question_count:
                type: integer
                description: Number of questions at this difficulty level.
        question_summary:
          type: array
          items:
            type: object
            properties:
              question_type:
                type: string
                description: Type of question (e.g., mcq_single_answer, true_false, etc.)
              learning_objectives:
                type: string
                description: Learning objectives associated with the question.
              bloom:
                type: string
                description: Bloom's taxonomy level for the question.
              difficulty:
                type: string
                description: Difficulty level (e.g., easy, medium, hard)
              question_count:
                type: integer
                description: Number of questions of this type.
      required:
        - question_type_summary
        - bloom_summary
        - difficulty_summary
        - question_summary
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````