diff --git a/pom.xml b/pom.xml
index b298731..6b41159 100644
--- a/pom.xml
+++ b/pom.xml
@@ -197,7 +197,15 @@
               <generateApiTests>true</generateApiTests>
               <generateApiDocumentation>true</generateApiDocumentation>
               <generateModels>true</generateModels>
-              <modelsToGenerate>entityDataType,arrayType,dateType,entityTypeRelation,objectType,nestedObjectProperty,entityTypeColumn,enumType,booleanType,entityType,integerType,openUUIDType,stringType,numberType,rangedUUIDType,valueWithLabel,entityTypeDefaultSort,errors,error,parameters,parameter,resultsetPage,queryDetails,queryIdentifier,sourceColumn,valueSourceApi,columnValues,columnValueGetter,submitQuery,contentsRequest,field,entityTypeSource,entityTypeSourceJoin,stringUUIDType</modelsToGenerate>
+              <modelsToGenerate>
+                <!-- the commas at the start and end of each line are load-bearing, as otherwise openapi-generator will include the newline/indentation as part of the model name -->
+                ,errors,error,parameters,parameter,resultsetPage,
+                ,entityType,field,entityTypeColumn,entityTypeRelation,entityTypeDefaultSort,sourceColumn,entityTypeSource,entityTypeSourceJoin,
+                ,entityDataType,arrayType,dateType,objectType,enumType,booleanType,integerType,openUUIDType,stringType,numberType,rangedUUIDType,stringUUIDType,
+                ,nestedObjectProperty,valueWithLabel,valueSourceApi,columnValues,columnValueGetter,
+                ,queryDetails,queryIdentifier,
+                ,submitQuery,contentsRequest,fqmMigrateRequest,fqmMigrateResponse,fqmMigrateWarning
+              </modelsToGenerate>
               <generateModelTests>false</generateModelTests>
               <generateModelDocumentation>true</generateModelDocumentation>
               <generateSupportingFiles>true</generateSupportingFiles>
diff --git a/src/main/resources/swagger.api/queryTool.yaml b/src/main/resources/swagger.api/queryTool.yaml
index 554d14d..6e9c180 100644
--- a/src/main/resources/swagger.api/queryTool.yaml
+++ b/src/main/resources/swagger.api/queryTool.yaml
@@ -352,6 +352,12 @@ components:
       $ref: schemas/query.json#/SubmitQuery
     contentsRequest:
       $ref: schemas/query.json#/ContentsRequest
+
+    fqmMigrateRequest:
+      $ref: schemas/fqmMigrateRequest.json
+    fqmMigrateResponse:
+      $ref: schemas/fqmMigrateResponse.json
+
     queryResultIds:
       type: array
       items:
@@ -375,7 +381,7 @@ components:
       content:
         application/json:
           schema:
-            $ref: "#/components/schemas/errors"
+            $ref: '#/components/schemas/errors'
     internalServerErrorResponse:
       description: When unhandled exception occurred during code execution, e.g. NullPointerException
       content:
@@ -386,5 +392,4 @@ components:
                 code: unexpected.error
             total_records: 1
           schema:
-            $ref: "#/components/schemas/errors"
-
+            $ref: '#/components/schemas/errors'
diff --git a/src/main/resources/swagger.api/schemas/fqmMigrateRequest.json b/src/main/resources/swagger.api/schemas/fqmMigrateRequest.json
new file mode 100644
index 0000000..ef56bb7
--- /dev/null
+++ b/src/main/resources/swagger.api/schemas/fqmMigrateRequest.json
@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Entity Upgrade Request",
+  "description": "Schema for a request to upgrade an entity payload, including an entity type ID, FQL query, and list of fields.",
+  "type": "object",
+  "properties": {
+    "entityTypeId": {
+      "description": "ID of the entity type to be upgraded",
+      "type": "string",
+      "format": "UUID"
+    },
+    "fqlQuery": {
+      "description": "FQL query string to be upgraded",
+      "type": "string"
+    },
+    "fields": {
+      "description": "List of fields to be upgraded",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "required": ["entityTypeId"]
+}
diff --git a/src/main/resources/swagger.api/schemas/fqmMigrateResponse.json b/src/main/resources/swagger.api/schemas/fqmMigrateResponse.json
new file mode 100644
index 0000000..c65a5e4
--- /dev/null
+++ b/src/main/resources/swagger.api/schemas/fqmMigrateResponse.json
@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Entity Upgrade Response",
+  "description": "Schema for a migrated query, with associated entity type, fields, and potential warnings",
+  "type": "object",
+  "properties": {
+    "entityTypeId": {
+      "description": "ID of the post-upgrade entity type",
+      "type": "string",
+      "format": "uuid"
+    },
+    "fqlQuery": {
+      "description": "Post-upgrade FQL query string",
+      "type": "string"
+    },
+    "fields": {
+      "description": "Post-upgrade list of fields",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "warnings": {
+      "description": "List of warnings issued during the upgrade",
+      "type": "array",
+      "items": {
+        "$ref": "./fqmMigrateWarning.json"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "required": ["entityTypeId"]
+}
diff --git a/src/main/resources/swagger.api/schemas/fqmMigrateWarning.json b/src/main/resources/swagger.api/schemas/fqmMigrateWarning.json
new file mode 100644
index 0000000..08d7a71
--- /dev/null
+++ b/src/main/resources/swagger.api/schemas/fqmMigrateWarning.json
@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Entity Upgrade Warning",
+  "description": "Warnings resulting from a query upgrade",
+  "type": "object",
+  "properties": {
+    "description": {
+      "description": "Description of the warning",
+      "type": "string"
+    },
+    "type": {
+      "description": "Type of warning",
+      "type": "string"
+    }
+  },
+  "additionalProperties": false,
+  "required": ["description", "type"]
+}