{
  "version": "1.0",
  "modules": [
    {
      "name": "Sessions",
      "prefix": "/sessions",
      "endpoints": [
        {
          "method": "POST",
          "path": "/",
          "summary": "Create Session",
          "description": "Creates a new user session with a unique session_id. Returns 409 if the session_id already exists. Initializes calculation_count to 0 and sets last_activity_at to current time.",
          "request_body": {
            "schema_name": "SessionCreate",
            "fields": [
              {
                "name": "session_id",
                "type": "str",
                "required": false
              }
            ]
          },
          "response": {
            "schema_name": "SessionResponse",
            "fields": [
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "session_id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "last_activity_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "calculation_count",
                "type": "int",
                "required": true
              }
            ],
            "is_list": false
          },
          "status_code": 201
        },
        {
          "method": "GET",
          "path": "/",
          "summary": "List Sessions",
          "description": "Returns a paginated list of all sessions ordered by creation date descending. Supports standard limit and offset pagination parameters.",
          "query_params": [
            {
              "name": "limit",
              "type": "int",
              "required": false,
              "default": 20
            },
            {
              "name": "offset",
              "type": "int",
              "required": false,
              "default": 0
            }
          ],
          "response": {
            "schema_name": "SessionResponse",
            "fields": [
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "session_id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "last_activity_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "calculation_count",
                "type": "int",
                "required": true
              }
            ],
            "is_list": true
          },
          "status_code": 200
        },
        {
          "method": "GET",
          "path": "/{entity_id}",
          "summary": "Get Session by ID",
          "description": "Retrieves a single session by its unique ID. Returns 404 if the session does not exist.",
          "path_params": [
            {
              "name": "entity_id",
              "type": "str"
            }
          ],
          "response": {
            "schema_name": "SessionResponse",
            "fields": [
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "session_id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "last_activity_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "calculation_count",
                "type": "int",
                "required": true
              }
            ],
            "is_list": false
          },
          "status_code": 200
        },
        {
          "method": "GET",
          "path": "/by-session-id/{session_id}",
          "summary": "Get Session by Session ID",
          "description": "Retrieves a single session by its session_id (UUID). Returns 404 if the session does not exist. Useful for client-side session lookup.",
          "path_params": [
            {
              "name": "session_id",
              "type": "str"
            }
          ],
          "response": {
            "schema_name": "SessionResponse",
            "fields": [
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "session_id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "last_activity_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "calculation_count",
                "type": "int",
                "required": true
              }
            ],
            "is_list": false
          },
          "status_code": 200
        },
        {
          "method": "PATCH",
          "path": "/{entity_id}",
          "summary": "Update Session",
          "description": "Updates session fields. Only provided fields are modified. Returns 404 if session not found, 409 if new session_id conflicts with existing session.",
          "path_params": [
            {
              "name": "entity_id",
              "type": "str"
            }
          ],
          "request_body": {
            "schema_name": "SessionUpdate",
            "fields": [
              {
                "name": "session_id",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "last_activity_at",
                "type": "datetime",
                "required": false,
                "nullable": true
              },
              {
                "name": "calculation_count",
                "type": "int",
                "required": false,
                "nullable": true
              }
            ]
          },
          "response": {
            "schema_name": "SessionResponse",
            "fields": [
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "session_id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "last_activity_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "calculation_count",
                "type": "int",
                "required": true
              }
            ],
            "is_list": false
          },
          "status_code": 200
        },
        {
          "method": "DELETE",
          "path": "/{entity_id}",
          "summary": "Delete Session",
          "description": "Deletes a session and all associated calculations via cascade delete. Returns 404 if the session does not exist.",
          "path_params": [
            {
              "name": "entity_id",
              "type": "str"
            }
          ],
          "status_code": 200
        },
        {
          "method": "GET",
          "path": "/{session_id}/history",
          "summary": "Get Session History",
          "description": "Retrieves a session with all its calculations ordered by timestamp descending. Returns session metadata and complete calculation history. Returns 404 if session not found.",
          "path_params": [
            {
              "name": "session_id",
              "type": "str"
            }
          ],
          "response": {
            "schema_name": "SessionHistoryResponse",
            "fields": [
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "session_id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "last_activity_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "calculation_count",
                "type": "int",
                "required": true
              },
              {
                "name": "calculations",
                "type": "list[SessionHistoryCalculation]",
                "required": true
              }
            ],
            "is_list": false
          },
          "status_code": 200
        },
        {
          "method": "DELETE",
          "path": "/{session_id}/history",
          "summary": "Clear Session History",
          "description": "Deletes all calculations for the specified session and resets calculation_count to 0. The session itself remains active. Returns 404 if session not found.",
          "path_params": [
            {
              "name": "session_id",
              "type": "str"
            }
          ],
          "status_code": 200
        }
      ]
    },
    {
      "name": "BMI Categories",
      "prefix": "/bmi-categories",
      "endpoints": [
        {
          "method": "POST",
          "path": "/",
          "summary": "Create BMI Category",
          "description": "Creates a new BMI category record with name, min/max values, description, and color code. Returns 409 if a category with the same name already exists.",
          "request_body": {
            "schema_name": "BmicategoryCreate",
            "fields": [
              {
                "name": "name",
                "type": "str",
                "required": false
              },
              {
                "name": "min_value",
                "type": "float",
                "required": false
              },
              {
                "name": "max_value",
                "type": "float",
                "required": false,
                "nullable": true
              },
              {
                "name": "description",
                "type": "str",
                "required": false
              },
              {
                "name": "color_code",
                "type": "str",
                "required": false
              }
            ]
          },
          "response": {
            "schema_name": "BmicategoryResponse",
            "fields": [
              {
                "name": "name",
                "type": "str",
                "required": false
              },
              {
                "name": "min_value",
                "type": "float",
                "required": false
              },
              {
                "name": "max_value",
                "type": "float",
                "required": false,
                "nullable": true
              },
              {
                "name": "description",
                "type": "str",
                "required": false
              },
              {
                "name": "color_code",
                "type": "str",
                "required": false
              },
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              }
            ],
            "is_list": false
          },
          "status_code": 201
        },
        {
          "method": "GET",
          "path": "/{bmicategory_id}",
          "summary": "Get BMI Category",
          "description": "Retrieves a single BMI category by its unique identifier. Returns 404 if the category does not exist.",
          "path_params": [
            {
              "name": "bmicategory_id",
              "type": "str"
            }
          ],
          "response": {
            "schema_name": "BmicategoryResponse",
            "fields": [
              {
                "name": "name",
                "type": "str",
                "required": false
              },
              {
                "name": "min_value",
                "type": "float",
                "required": false
              },
              {
                "name": "max_value",
                "type": "float",
                "required": false,
                "nullable": true
              },
              {
                "name": "description",
                "type": "str",
                "required": false
              },
              {
                "name": "color_code",
                "type": "str",
                "required": false
              },
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              }
            ],
            "is_list": false
          },
          "status_code": 200
        },
        {
          "method": "GET",
          "path": "/",
          "summary": "List BMI Categories",
          "description": "Returns a paginated list of all BMI categories ordered by minimum BMI value. Supports limit and offset for pagination.",
          "query_params": [
            {
              "name": "limit",
              "type": "int",
              "required": false,
              "default": 20
            },
            {
              "name": "offset",
              "type": "int",
              "required": false,
              "default": 0
            }
          ],
          "response": {
            "schema_name": "BmicategoryResponse",
            "fields": [
              {
                "name": "name",
                "type": "str",
                "required": false
              },
              {
                "name": "min_value",
                "type": "float",
                "required": false
              },
              {
                "name": "max_value",
                "type": "float",
                "required": false,
                "nullable": true
              },
              {
                "name": "description",
                "type": "str",
                "required": false
              },
              {
                "name": "color_code",
                "type": "str",
                "required": false
              },
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              }
            ],
            "is_list": true
          },
          "status_code": 200
        },
        {
          "method": "PUT",
          "path": "/{bmicategory_id}",
          "summary": "Update BMI Category",
          "description": "Updates an existing BMI category. Only provided fields are updated. Returns 404 if the category does not exist, 409 if the new name conflicts with an existing category.",
          "path_params": [
            {
              "name": "bmicategory_id",
              "type": "str"
            }
          ],
          "request_body": {
            "schema_name": "BmicategoryUpdate",
            "fields": [
              {
                "name": "name",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "min_value",
                "type": "float",
                "required": false,
                "nullable": true
              },
              {
                "name": "max_value",
                "type": "float",
                "required": false,
                "nullable": true
              },
              {
                "name": "description",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "color_code",
                "type": "str",
                "required": false,
                "nullable": true
              }
            ]
          },
          "response": {
            "schema_name": "BmicategoryResponse",
            "fields": [
              {
                "name": "name",
                "type": "str",
                "required": false
              },
              {
                "name": "min_value",
                "type": "float",
                "required": false
              },
              {
                "name": "max_value",
                "type": "float",
                "required": false,
                "nullable": true
              },
              {
                "name": "description",
                "type": "str",
                "required": false
              },
              {
                "name": "color_code",
                "type": "str",
                "required": false
              },
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              }
            ],
            "is_list": false
          },
          "status_code": 200
        },
        {
          "method": "DELETE",
          "path": "/{bmicategory_id}",
          "summary": "Delete BMI Category",
          "description": "Deletes a BMI category by its unique identifier. Returns 404 if the category does not exist.",
          "path_params": [
            {
              "name": "bmicategory_id",
              "type": "str"
            }
          ],
          "status_code": 204
        }
      ]
    }
  ],
  "enums": {
    "HeightUnit": [
      "CM",
      "INCHES"
    ],
    "WeightUnit": [
      "KG",
      "LBS"
    ]
  }
}