{
  "openapi": "3.0.0",
  "info": {
    "title": "SpecGen API",
    "version": "1.0.0",
    "description": "API documentation for SpecGen - a speculative fiction generator",
    "license": {
      "name": "ISC",
      "url": "https://opensource.org/licenses/ISC"
    }
  },
  "servers": [
    {
      "url": "http://localhost:3000",
      "description": "Local development server"
    }
  ],
  "components": {
    "schemas": {
      "Category": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the category",
            "example": "science-fiction"
          },
          "name": {
            "type": "string",
            "description": "Display name of the category",
            "example": "Science Fiction"
          },
          "description": {
            "type": "string",
            "description": "Optional description of the category",
            "example": "Stories set in the future with advanced technology"
          },
          "visibility": {
            "type": "string",
            "description": "Whether to show or hide this category in the UI",
            "enum": [
              "Show",
              "Hide"
            ],
            "example": "Show"
          },
          "year": {
            "type": "integer",
            "description": "Year associated with this category",
            "example": 2050
          }
        },
        "required": [
          "id",
          "name",
          "visibility"
        ]
      },
      "Parameter": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the parameter",
            "example": "science-fiction-technology-level"
          },
          "name": {
            "type": "string",
            "description": "Display name of the parameter",
            "example": "Technology Level"
          },
          "description": {
            "type": "string",
            "description": "Optional description of the parameter",
            "example": "The level of technological advancement in the story"
          },
          "visibility": {
            "type": "string",
            "description": "Visibility level of this parameter",
            "enum": [
              "Basic",
              "Advanced"
            ],
            "example": "Basic"
          },
          "type": {
            "type": "string",
            "description": "Type of the parameter input",
            "enum": [
              "Dropdown",
              "Slider",
              "Toggle Switch",
              "Radio Buttons",
              "Checkbox"
            ],
            "example": "Dropdown"
          },
          "categoryId": {
            "type": "string",
            "description": "ID of the category this parameter belongs to",
            "example": "science-fiction"
          },
          "values": {
            "oneOf": [
              {
                "type": "array",
                "description": "For Dropdown, Radio Buttons, and Checkbox types",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "example": "near-future"
                    },
                    "label": {
                      "type": "string",
                      "example": "Near Future"
                    }
                  }
                },
                "example": [
                  {
                    "id": "near-future",
                    "label": "Near Future"
                  },
                  {
                    "id": "advanced",
                    "label": "Advanced"
                  }
                ]
              },
              {
                "type": "object",
                "description": "For Toggle Switch type",
                "properties": {
                  "on": {
                    "type": "string",
                    "example": "Yes"
                  },
                  "off": {
                    "type": "string",
                    "example": "No"
                  }
                },
                "example": {
                  "on": "Yes",
                  "off": "No"
                }
              }
            ]
          },
          "config": {
            "type": "object",
            "description": "Configuration for Slider type",
            "properties": {
              "min": {
                "type": "number",
                "example": 0
              },
              "max": {
                "type": "number",
                "example": 100
              },
              "step": {
                "type": "number",
                "example": 1
              }
            },
            "example": {
              "min": 0,
              "max": 100,
              "step": 1
            }
          }
        },
        "required": [
          "id",
          "name",
          "type",
          "categoryId"
        ]
      },
      "Content": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the content",
            "example": "content-1648236587000-123"
          },
          "title": {
            "type": "string",
            "description": "Title of the generated content",
            "example": "Space Explorer Adventure"
          },
          "type": {
            "type": "string",
            "description": "Type of content (fiction or image)",
            "enum": [
              "fiction",
              "image"
            ],
            "example": "fiction"
          },
          "content": {
            "type": "string",
            "description": "The generated fiction content (only for fiction type)",
            "example": "The starship Nebula drifted silently through the endless void of space..."
          },
          "imageUrl": {
            "type": "string",
            "description": "URL of the generated image (only for image type)",
            "example": "https://example.com/generated-image.jpg"
          },
          "year": {
            "type": "integer",
            "description": "Year in which the story is set",
            "example": 2085
          },
          "parameterValues": {
            "type": "object",
            "description": "Parameters used to generate this content",
            "example": {
              "science-fiction": {
                "science-fiction-technology-level": "Near Future",
                "science-fiction-alien-life": true
              }
            }
          },
          "metadata": {
            "type": "object",
            "description": "Additional metadata about the generation",
            "example": {
              "model": "gpt-4o-mini",
              "tokens": 1250
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the content was created",
            "example": "2023-04-15T12:34:56.789Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the content was last updated",
            "example": "2023-04-15T12:34:56.789Z"
          }
        },
        "required": [
          "id",
          "title",
          "type",
          "parameterValues",
          "createdAt",
          "updatedAt"
        ]
      },
      "ContentList": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/Content"
        }
      },
      "ContentResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/Content"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContentListResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/ContentList"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContentDeleteResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "message": {
            "type": "string",
            "example": "Content 'Space Explorer Adventure' deleted successfully"
          },
          "data": {
            "type": "object",
            "properties": {
              "deletedContent": {
                "$ref": "#/components/schemas/Content"
              }
            }
          }
        },
        "required": [
          "success",
          "message",
          "data"
        ]
      },
      "GenerationParameters": {
        "type": "object",
        "description": "Object containing parameterValues object that maps category IDs to parameter selections. The parameterValues object has category IDs as keys, with each value being an object of parameter ID/value pairs.\n",
        "properties": {
          "parameterValues": {
            "type": "object",
            "description": "Map of category IDs to parameter selections",
            "example": {
              "science-fiction": {
                "science-fiction-technology-level": "Near Future",
                "science-fiction-alien-life": true,
                "science-fiction-space-exploration-focus": 7
              },
              "fantasy": {
                "fantasy-magic-system": "Elemental",
                "fantasy-mythical-creatures": [
                  "Dragons",
                  "Elves"
                ]
              }
            }
          },
          "contentType": {
            "type": "string",
            "description": "Type of content to generate ('fiction', 'image', or 'combined')",
            "enum": [
              "fiction",
              "image",
              "combined"
            ],
            "default": "fiction"
          },
          "year": {
            "type": "integer",
            "description": "Year in which the story is set (e.g., 2050, 2100)",
            "example": 2085
          },
          "title": {
            "type": "string",
            "description": "Optional title to use for the story (if not provided, one will be generated)",
            "example": "The Last Frontier"
          }
        },
        "required": [
          "parameterValues"
        ]
      },
      "GenerationResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Whether the generation was successful",
            "example": true
          },
          "content": {
            "type": "string",
            "description": "Generated story content (only provided for fiction or combined type)",
            "example": "The starship Nebula drifted silently through the endless void of space..."
          },
          "imageData": {
            "type": "string",
            "description": "Base64-encoded image data (only provided for image or combined type)",
            "example": "iVBORw0KGgoAAAANSUhEUgAA..."
          },
          "title": {
            "type": "string",
            "description": "Title of the generated story (either provided or extracted from content)",
            "example": "The Last Frontier"
          },
          "year": {
            "type": "integer",
            "description": "Year in which the story is set",
            "example": 2085
          },
          "metadata": {
            "type": "object",
            "properties": {
              "model": {
                "type": "string",
                "description": "The AI model used for generation (for fiction or image type)",
                "example": "gpt-4o-mini"
              },
              "tokens": {
                "type": "integer",
                "description": "Total tokens used for this generation (for fiction type)",
                "example": 1250
              },
              "prompt": {
                "type": "string",
                "description": "Prompt used for image generation (for image type)",
                "example": "A futuristic city with flying vehicles..."
              },
              "fiction": {
                "type": "object",
                "description": "Fiction generation metadata (for combined type)",
                "properties": {
                  "model": {
                    "type": "string",
                    "example": "gpt-4o-mini"
                  },
                  "tokens": {
                    "type": "integer",
                    "example": 1250
                  }
                }
              },
              "image": {
                "type": "object",
                "description": "Image generation metadata (for combined type)",
                "properties": {
                  "model": {
                    "type": "string",
                    "example": "dall-e-3"
                  },
                  "prompt": {
                    "type": "string",
                    "example": "A fantasy landscape with dragons and elves..."
                  }
                }
              }
            }
          }
        },
        "required": [
          "success",
          "metadata"
        ]
      },
      "GenerationError": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "Invalid parameters: Parameter 'param-123456' not found"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "Settings": {
        "type": "object",
        "properties": {
          "ai": {
            "type": "object",
            "properties": {
              "models": {
                "type": "object",
                "properties": {
                  "fiction": {
                    "type": "string",
                    "description": "AI model for fiction generation",
                    "example": "gpt-4o-mini"
                  },
                  "image": {
                    "type": "string",
                    "description": "AI model for image generation",
                    "example": "dall-e-3"
                  }
                }
              },
              "parameters": {
                "type": "object",
                "properties": {
                  "fiction": {
                    "type": "object",
                    "properties": {
                      "temperature": {
                        "type": "number",
                        "description": "Temperature for fiction generation",
                        "example": 0.8
                      },
                      "max_tokens": {
                        "type": "integer",
                        "description": "Maximum tokens for fiction generation",
                        "example": 1000
                      },
                      "default_story_length": {
                        "type": "integer",
                        "description": "Default story length in words",
                        "example": 500
                      }
                    }
                  },
                  "image": {
                    "type": "object",
                    "properties": {
                      "size": {
                        "type": "string",
                        "description": "Image size for generation",
                        "example": "1024x1024"
                      },
                      "quality": {
                        "type": "string",
                        "description": "Image quality for generation",
                        "enum": [
                          "standard",
                          "hd"
                        ],
                        "example": "standard"
                      }
                    }
                  }
                }
              }
            }
          },
          "defaults": {
            "type": "object",
            "properties": {
              "content_type": {
                "type": "string",
                "description": "Default content type for generation",
                "enum": [
                  "fiction",
                  "image"
                ],
                "example": "fiction"
              }
            }
          }
        }
      },
      "SettingsResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/Settings"
          }
        }
      },
      "SettingsUpdateRequest": {
        "type": "object",
        "description": "Partial settings update, only include fields to update",
        "example": {
          "ai": {
            "parameters": {
              "fiction": {
                "temperature": 0.9,
                "max_tokens": 1500
              }
            }
          }
        }
      },
      "SettingsResetResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "message": {
            "type": "string",
            "example": "Settings reset to defaults"
          },
          "data": {
            "$ref": "#/components/schemas/Settings"
          }
        }
      }
    },
    "responses": {
      "Error": {
        "description": "Error response",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "success": {
                  "type": "boolean",
                  "example": false
                },
                "error": {
                  "type": "string",
                  "example": "Error message details"
                }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/categories": {
      "get": {
        "summary": "Get all categories",
        "tags": [
          "Categories"
        ],
        "responses": {
          "200": {
            "description": "List of categories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Category"
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "post": {
        "summary": "Create a new category",
        "tags": [
          "Categories"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Science Fiction"
                  },
                  "description": {
                    "type": "string",
                    "example": "Stories set in the future with advanced technology"
                  },
                  "visibility": {
                    "type": "string",
                    "enum": [
                      "Show",
                      "Hide"
                    ],
                    "default": "Show",
                    "example": "Show"
                  }
                }
              },
              "examples": {
                "basicCategory": {
                  "summary": "Basic category with just a name",
                  "value": {
                    "name": "Science Fiction"
                  }
                },
                "fullCategory": {
                  "summary": "Complete category with all fields",
                  "value": {
                    "name": "Fantasy",
                    "description": "Stories with magic and mythical creatures",
                    "visibility": "Show"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Category created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Category"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/categories/{id}": {
      "get": {
        "summary": "Get a category by ID",
        "tags": [
          "Categories"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Category ID",
            "example": "science-fiction"
          }
        ],
        "responses": {
          "200": {
            "description": "Category details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Category"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "put": {
        "summary": "Update a category",
        "tags": [
          "Categories"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Category ID",
            "example": "science-fiction"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Updated Science Fiction"
                  },
                  "description": {
                    "type": "string",
                    "example": "Updated description for science fiction category"
                  },
                  "visibility": {
                    "type": "string",
                    "enum": [
                      "Show",
                      "Hide"
                    ],
                    "example": "Show"
                  }
                }
              },
              "example": {
                "name": "Updated Science Fiction",
                "description": "Updated description for science fiction category",
                "visibility": "Show"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Category updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Category"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "delete": {
        "summary": "Delete a category and its parameters",
        "tags": [
          "Categories"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Category ID",
            "example": "science-fiction"
          }
        ],
        "responses": {
          "200": {
            "description": "Category deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Category 'Science Fiction' deleted successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "deletedCategory": {
                          "$ref": "#/components/schemas/Category"
                        },
                        "deletedParameters": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Parameter"
                          }
                        },
                        "parameterCount": {
                          "type": "integer",
                          "example": 3
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/content": {
      "get": {
        "summary": "Get all generated content",
        "description": "Retrieve a list of all generated content, with optional filtering by type or year",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "type",
            "schema": {
              "type": "string",
              "enum": [
                "fiction",
                "image"
              ]
            },
            "description": "Filter content by type"
          },
          {
            "in": "query",
            "name": "year",
            "schema": {
              "type": "integer"
            },
            "description": "Filter content by story year"
          }
        ],
        "responses": {
          "200": {
            "description": "List of generated content",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentListResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/content/years": {
      "get": {
        "summary": "Get all years with content",
        "description": "Retrieve a list of all years that have generated content",
        "tags": [
          "Content"
        ],
        "responses": {
          "200": {
            "description": "List of years with content",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "integer"
                      },
                      "example": [
                        2050,
                        2085,
                        2100,
                        2150
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/content/year/{year}": {
      "get": {
        "summary": "Get content by year",
        "description": "Retrieve all content set in a specific year",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "year",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Year to filter by"
          }
        ],
        "responses": {
          "200": {
            "description": "List of content for the specified year",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentListResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/content/{id}": {
      "get": {
        "summary": "Get a specific generated content",
        "description": "Retrieve a single generated content item by its ID",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Content ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Generated content",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentResponse"
                }
              }
            }
          },
          "404": {
            "description": "Content not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/responses/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "put": {
        "summary": "Update generated content",
        "description": "Update a generated content's title, content, imageUrl, or year",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Content ID"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "New title for the content",
                    "example": "Updated Space Adventure"
                  },
                  "content": {
                    "type": "string",
                    "description": "New content (for fiction type only)",
                    "example": "Updated story content..."
                  },
                  "imageUrl": {
                    "type": "string",
                    "description": "New image URL (for image type only)",
                    "example": "https://example.com/new-image.jpg"
                  },
                  "year": {
                    "type": "integer",
                    "description": "New year for the story setting",
                    "example": 2095
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated content",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentResponse"
                }
              }
            }
          },
          "404": {
            "description": "Content not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/responses/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "delete": {
        "summary": "Delete generated content",
        "description": "Delete a generated content item by its ID",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Content ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Content deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentDeleteResponse"
                }
              }
            }
          },
          "404": {
            "description": "Content not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/responses/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/database/download": {
      "get": {
        "summary": "Download the database file",
        "description": "Retrieve the current database file in JSON format.",
        "responses": {
          "200": {
            "description": "Database data retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No database data found."
          },
          "500": {
            "description": "Failed to download database."
          }
        }
      }
    },
    "/api/database/generations/download": {
      "get": {
        "summary": "Download the generations database",
        "description": "Retrieve all generated content from the SQLite database in JSON format.",
        "responses": {
          "200": {
            "description": "Generations data retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No generations data found."
          },
          "500": {
            "description": "Failed to download generations database."
          }
        }
      }
    },
    "/api/database/restore": {
      "post": {
        "summary": "Restore the database from a file",
        "description": "Restore the database using an uploaded JSON file. The file should contain valid \"categories\" and \"parameters\" arrays.",
        "consumes": [
          "multipart/form-data"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Database restored successfully."
          },
          "400": {
            "description": "No file uploaded, invalid JSON file, or invalid database structure."
          },
          "500": {
            "description": "Failed to restore database."
          }
        }
      }
    },
    "/api/database/generations/restore": {
      "post": {
        "summary": "Restore the generations database from a file",
        "description": "Restore the generations database using an uploaded JSON file. The file should contain a valid \"generations\" array.",
        "consumes": [
          "multipart/form-data"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generations database restored successfully."
          },
          "400": {
            "description": "No file uploaded, invalid JSON file, or invalid database structure."
          },
          "500": {
            "description": "Failed to restore generations database."
          }
        }
      }
    },
    "/api/database/reset": {
      "post": {
        "summary": "Reset the database to an empty state",
        "description": "Clear all data from the database by resetting it to an empty state.",
        "responses": {
          "200": {
            "description": "Database reset successfully."
          },
          "500": {
            "description": "Failed to reset database."
          }
        }
      }
    },
    "/api/database/generations/reset": {
      "post": {
        "summary": "Reset the generations database to an empty state",
        "description": "Clear all data from the generations database by resetting it to an empty state.",
        "responses": {
          "200": {
            "description": "Generations database reset successfully."
          },
          "500": {
            "description": "Failed to reset generations database."
          }
        }
      }
    },
    "/api/database/reset-all": {
      "post": {
        "summary": "Reset all databases to an empty state",
        "description": "Clear all data from both the primary database and generations database.",
        "responses": {
          "200": {
            "description": "All databases reset successfully."
          },
          "500": {
            "description": "Failed to reset databases."
          }
        }
      }
    },
    "/api/generate": {
      "post": {
        "summary": "Generate fiction text or an image based on selected parameters",
        "description": "Sends the provided parameter selections to the AI service and returns either a generated story or image URL based on the contentType. The request body must contain a 'parameterValues' object with category IDs as keys, and each category having parameter IDs as keys with their respective values.\n",
        "tags": [
          "Generation"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "parameterValues"
                ],
                "properties": {
                  "parameterValues": {
                    "type": "object",
                    "description": "Map of category IDs to parameter selections"
                  },
                  "contentType": {
                    "type": "string",
                    "enum": [
                      "fiction",
                      "image",
                      "combined"
                    ],
                    "default": "fiction",
                    "description": "Type of content to generate ('fiction', 'image', or 'combined')"
                  },
                  "year": {
                    "type": "integer",
                    "description": "Optional year in which to set the story",
                    "example": 2085
                  },
                  "title": {
                    "type": "string",
                    "description": "Optional title to use for the story (if not provided, one will be generated)",
                    "example": "The Last Frontier"
                  }
                }
              },
              "examples": {
                "fictionGeneration": {
                  "summary": "Fiction generation request",
                  "value": {
                    "parameterValues": {
                      "science-fiction": {
                        "science-fiction-technology-level": "Near Future",
                        "science-fiction-alien-life": true,
                        "science-fiction-space-exploration-focus": 7
                      }
                    },
                    "contentType": "fiction",
                    "year": 2085
                  }
                },
                "imageGeneration": {
                  "summary": "Image generation request",
                  "value": {
                    "parameterValues": {
                      "fantasy": {
                        "fantasy-magic-system": "Elemental",
                        "fantasy-mythical-creatures": [
                          "Dragons",
                          "Elves"
                        ]
                      }
                    },
                    "contentType": "image",
                    "year": 2150
                  }
                },
                "combinedGeneration": {
                  "summary": "Combined fiction and image generation request",
                  "value": {
                    "parameterValues": {
                      "fantasy": {
                        "fantasy-magic-system": "Elemental",
                        "fantasy-mythical-creatures": [
                          "Dragons",
                          "Elves"
                        ]
                      }
                    },
                    "contentType": "combined",
                    "year": 2100,
                    "title": "The Crystal Caves of Eldoria"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Content generated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenerationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenerationError"
                }
              }
            }
          },
          "500": {
            "description": "AI service error or other server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenerationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "Get server health status",
        "description": "Retrieves system health information and server status",
        "tags": [
          "Health"
        ],
        "responses": {
          "200": {
            "description": "Health check successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "healthy"
                    },
                    "version": {
                      "type": "string",
                      "example": "1.0.0"
                    },
                    "uptime": {
                      "type": "number",
                      "description": "Server uptime in seconds",
                      "example": 3600
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time",
                      "example": "2023-04-25T12:34:56.789Z"
                    },
                    "memory": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "number",
                          "description": "Total memory in MB",
                          "example": 8192
                        },
                        "free": {
                          "type": "number",
                          "description": "Free memory in MB",
                          "example": 4096
                        },
                        "usage": {
                          "type": "number",
                          "description": "Memory usage percentage",
                          "example": 50
                        }
                      }
                    },
                    "system": {
                      "type": "object",
                      "properties": {
                        "platform": {
                          "type": "string",
                          "example": "linux"
                        },
                        "arch": {
                          "type": "string",
                          "example": "x64"
                        },
                        "cpus": {
                          "type": "number",
                          "example": 4
                        }
                      }
                    },
                    "services": {
                      "type": "object",
                      "properties": {
                        "database": {
                          "type": "string",
                          "example": "connected"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Health check failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "unhealthy"
                    },
                    "error": {
                      "type": "string",
                      "example": "Database connection failed"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/health/ping": {
      "get": {
        "summary": "Simple ping endpoint",
        "description": "Returns a simple response to verify the server is running",
        "tags": [
          "Health"
        ],
        "responses": {
          "200": {
            "description": "Successful ping response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "pong"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/parameters": {
      "get": {
        "summary": "Get all parameters or filter by categoryId",
        "tags": [
          "Parameters"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "categoryId",
            "schema": {
              "type": "string"
            },
            "description": "Optional category ID to filter parameters"
          }
        ],
        "responses": {
          "200": {
            "description": "List of parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Parameter"
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "post": {
        "summary": "Create a new parameter",
        "tags": [
          "Parameters"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "type",
                  "categoryId"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Character Type"
                  },
                  "description": {
                    "type": "string",
                    "example": "The type of main character in the story"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "Dropdown",
                      "Slider",
                      "Toggle Switch",
                      "Radio Buttons",
                      "Checkbox"
                    ],
                    "example": "Dropdown"
                  },
                  "visibility": {
                    "type": "string",
                    "enum": [
                      "Basic",
                      "Advanced"
                    ],
                    "default": "Basic",
                    "example": "Basic"
                  },
                  "categoryId": {
                    "type": "string",
                    "example": "science-fiction"
                  },
                  "required": {
                    "type": "boolean",
                    "description": "Whether this parameter is required",
                    "default": false,
                    "example": true
                  },
                  "values": {
                    "oneOf": [
                      {
                        "type": "array",
                        "description": "For Dropdown, Radio Buttons, and Checkbox types",
                        "items": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "example": "hero"
                            },
                            "label": {
                              "type": "string",
                              "example": "Hero"
                            }
                          }
                        },
                        "example": [
                          {
                            "label": "Hero"
                          },
                          {
                            "label": "Villain"
                          },
                          {
                            "label": "Sidekick"
                          }
                        ]
                      },
                      {
                        "type": "object",
                        "description": "For Toggle Switch type",
                        "properties": {
                          "on": {
                            "type": "string",
                            "example": "Yes"
                          },
                          "off": {
                            "type": "string",
                            "example": "No"
                          }
                        },
                        "example": {
                          "on": "Yes",
                          "off": "No"
                        }
                      }
                    ]
                  },
                  "config": {
                    "type": "object",
                    "description": "For Slider type",
                    "properties": {
                      "min": {
                        "type": "number",
                        "example": 100
                      },
                      "max": {
                        "type": "number",
                        "example": 10000
                      },
                      "step": {
                        "type": "number",
                        "example": 100
                      }
                    },
                    "example": {
                      "min": 100,
                      "max": 10000,
                      "step": 100
                    }
                  }
                }
              },
              "examples": {
                "dropdown": {
                  "summary": "Example Dropdown Parameter",
                  "value": {
                    "name": "Character Type",
                    "type": "Dropdown",
                    "visibility": "Basic",
                    "categoryId": "science-fiction",
                    "required": true,
                    "values": [
                      {
                        "label": "Hero"
                      },
                      {
                        "label": "Villain"
                      },
                      {
                        "label": "Sidekick"
                      }
                    ]
                  }
                },
                "slider": {
                  "summary": "Example Slider Parameter",
                  "value": {
                    "name": "Story Length",
                    "type": "Slider",
                    "visibility": "Basic",
                    "categoryId": "science-fiction",
                    "required": false,
                    "config": {
                      "min": 100,
                      "max": 10000,
                      "step": 100
                    }
                  }
                },
                "toggle": {
                  "summary": "Example Toggle Parameter",
                  "value": {
                    "name": "Happy Ending",
                    "type": "Toggle Switch",
                    "visibility": "Basic",
                    "categoryId": "science-fiction",
                    "required": false,
                    "values": {
                      "on": "Yes",
                      "off": "No"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Parameter created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Parameter"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/parameters/{id}": {
      "get": {
        "summary": "Get a parameter by ID",
        "tags": [
          "Parameters"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Parameter ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Parameter details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Parameter"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "put": {
        "summary": "Update a parameter",
        "tags": [
          "Parameters"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Parameter ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Updated Character Type"
                  },
                  "description": {
                    "type": "string",
                    "example": "Updated description"
                  },
                  "visibility": {
                    "type": "string",
                    "enum": [
                      "Basic",
                      "Advanced"
                    ],
                    "example": "Advanced"
                  },
                  "required": {
                    "type": "boolean",
                    "example": true
                  },
                  "values": {
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "example": "updated-hero"
                            },
                            "label": {
                              "type": "string",
                              "example": "Updated Hero"
                            }
                          }
                        },
                        "example": [
                          {
                            "label": "Updated Hero"
                          },
                          {
                            "label": "Updated Villain"
                          }
                        ]
                      },
                      {
                        "type": "object",
                        "properties": {
                          "on": {
                            "type": "string",
                            "example": "Updated Yes"
                          },
                          "off": {
                            "type": "string",
                            "example": "Updated No"
                          }
                        },
                        "example": {
                          "on": "Updated Yes",
                          "off": "Updated No"
                        }
                      }
                    ]
                  },
                  "config": {
                    "type": "object",
                    "properties": {
                      "min": {
                        "type": "number",
                        "example": 200
                      },
                      "max": {
                        "type": "number",
                        "example": 20000
                      },
                      "step": {
                        "type": "number",
                        "example": 200
                      }
                    },
                    "example": {
                      "min": 200,
                      "max": 20000,
                      "step": 200
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Parameter updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Parameter"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "delete": {
        "summary": "Delete a parameter",
        "tags": [
          "Parameters"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Parameter ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Parameter deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "deletedParameter": {
                          "$ref": "#/components/schemas/Parameter"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/settings": {
      "get": {
        "summary": "Get all application settings",
        "tags": [
          "Settings"
        ],
        "responses": {
          "200": {
            "description": "All application settings",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettingsResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "put": {
        "summary": "Update application settings",
        "tags": [
          "Settings"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SettingsUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated application settings",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettingsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/settings/reset": {
      "post": {
        "summary": "Reset settings to defaults",
        "tags": [
          "Settings"
        ],
        "responses": {
          "200": {
            "description": "Settings reset to defaults",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettingsResetResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Content",
      "description": "Generated content management endpoints"
    },
    {
      "name": "Generation",
      "description": "Story and image generation endpoints"
    },
    {
      "name": "Health",
      "description": "Server health monitoring endpoints"
    },
    {
      "name": "Settings",
      "description": "Application settings management"
    }
  ],
  "_meta": {
    "generatedAt": "2025-05-29T03:49:46.107Z",
    "version": "0.10.4"
  }
}