{
  "openapi": "3.1.0",
  "info": {
    "title": "MessyPoly API",
    "version": "2026-07-23",
    "description": "Customer automation API. Authenticate with Authorization: Bearer mpk_…. Mutating routes require Idempotency-Key. Full shipped product surface — actions, assets, batches, print quote/setups, webhooks.",
    "x-action-credit-costs": {
      "economyVersion": 2,
      "quick": 1,
      "optimize": 5,
      "retopo": 15,
      "generate": 75,
      "actions": {
        "generate": 75,
        "optimize": 5,
        "retopo": 15,
        "inspect": 0,
        "repair": 1,
        "fill_holes": 1,
        "unwrap": 1,
        "appearance": 1,
        "resize": 1,
        "add_base": 1,
        "hollow": 1,
        "print_prepare": 1,
        "print_check": 0,
        "print_recipe": "quote",
        "split": 1,
        "rig": 1,
        "animate": 1
      }
    }
  },
  "servers": [{ "url": "https://api.messypoly.com" }],
  "paths": {
    "/api/v1/imports": {
      "post": {
        "summary": "Create a model or image import (presigned upload)",
        "operationId": "createImport",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["filename", "sizeBytes"],
                "properties": {
                  "filename": { "type": "string" },
                  "sizeBytes": { "type": "integer", "minimum": 1 },
                  "contentType": {
                    "type": "string",
                    "description": "model/gltf-binary for GLB, or image/* for generate"
                  },
                  "sha256": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Import created" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/imports/{importId}/complete": {
      "post": {
        "summary": "Confirm the upload object is present",
        "operationId": "completeImport",
        "parameters": [
          { "name": "importId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "responses": { "200": { "description": "Import ready" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/imports/{importId}": {
      "get": {
        "summary": "Get import status",
        "operationId": "getImport",
        "parameters": [
          { "name": "importId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Import status" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/imports/{importId}/actions": {
      "post": {
        "summary": "Start generate (or inspect/optimize) on a pending import",
        "operationId": "createImportAction",
        "parameters": [
          { "name": "importId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ActionRequest" }
            }
          }
        },
        "responses": { "200": { "description": "Job queued" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/assets": {
      "get": {
        "summary": "List assets",
        "operationId": "listAssets",
        "responses": { "200": { "description": "Asset page" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/assets/{assetId}": {
      "get": {
        "summary": "Get asset",
        "operationId": "getAsset",
        "parameters": [
          { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Asset" } },
        "security": [{ "apiKey": [] }]
      },
      "patch": {
        "summary": "Update asset name, tags, project, or featured version",
        "operationId": "patchAsset",
        "parameters": [
          { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetPatchRequest" } } }
        },
        "responses": { "200": { "description": "Updated asset" } },
        "security": [{ "apiKey": [] }]
      },
      "delete": {
        "summary": "Delete an asset",
        "operationId": "deleteAsset",
        "parameters": [
          { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "responses": { "200": { "description": "Deleted" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/assets/{assetId}/versions": {
      "get": {
        "summary": "List asset versions",
        "operationId": "listAssetVersions",
        "parameters": [
          { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Versions" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/versions/{versionId}": {
      "patch": {
        "summary": "Update version label or notes",
        "operationId": "patchVersion",
        "parameters": [
          { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionPatchRequest" } } }
        },
        "responses": { "200": { "description": "Updated version" } },
        "security": [{ "apiKey": [] }]
      },
      "delete": {
        "summary": "Delete a version",
        "operationId": "deleteVersion",
        "parameters": [
          { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "mode", "in": "query", "schema": { "type": "string", "enum": ["files", "branch"] } },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "responses": { "200": { "description": "Deleted" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/versions/{versionId}/actions": {
      "post": {
        "summary": "Start an action from a retained version",
        "operationId": "createVersionAction",
        "parameters": [
          { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ActionRequest" }
            }
          }
        },
        "responses": { "200": { "description": "Job queued" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/projects": {
      "get": {
        "summary": "List projects",
        "operationId": "listProjects",
        "responses": { "200": { "description": "Projects" } },
        "security": [{ "apiKey": [] }]
      },
      "post": {
        "summary": "Create a project",
        "operationId": "createProject",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRequest" } } }
        },
        "responses": { "200": { "description": "Created" }, "201": { "description": "Created" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/projects/{projectId}": {
      "patch": {
        "summary": "Rename a project",
        "operationId": "patchProject",
        "parameters": [
          { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRequest" } } }
        },
        "responses": { "200": { "description": "Updated" } },
        "security": [{ "apiKey": [] }]
      },
      "delete": {
        "summary": "Delete a project",
        "operationId": "deleteProject",
        "parameters": [
          { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "responses": { "200": { "description": "Deleted" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/batches": {
      "post": {
        "summary": "Create a batch optimize job set",
        "operationId": "createBatch",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRequest" } } }
        },
        "responses": { "200": { "description": "Batch created" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/batches/{batchId}": {
      "get": {
        "summary": "Get batch status",
        "operationId": "getBatch",
        "parameters": [
          { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Batch" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/batches/{batchId}/archive": {
      "get": {
        "summary": "Download batch archive",
        "operationId": "getBatchArchive",
        "parameters": [
          { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "ZIP archive" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/print-recipes/quote": {
      "post": {
        "summary": "Quote a print recipe before print_recipe action",
        "operationId": "quotePrintRecipe",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintRecipeQuoteRequest" } } }
        },
        "responses": { "200": { "description": "Quote" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/print-setups": {
      "get": {
        "summary": "List printer setups",
        "operationId": "listPrintSetups",
        "responses": { "200": { "description": "Setups" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/jobs/{jobId}": {
      "get": {
        "summary": "Get job status",
        "operationId": "getJob",
        "parameters": [
          { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Job" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/jobs/{jobId}/cancel": {
      "post": {
        "summary": "Cancel a job",
        "operationId": "cancelJob",
        "parameters": [
          { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "responses": { "200": { "description": "Canceled" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/jobs/{jobId}/artifacts": {
      "get": {
        "summary": "List job artifact download URLs",
        "operationId": "getJobArtifacts",
        "parameters": [
          { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Artifacts" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/jobs/{jobId}/appearance-inputs": {
      "post": {
        "summary": "Presign an appearance replacement image upload",
        "operationId": "createAppearanceInput",
        "parameters": [
          { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppearanceInputRequest" } } }
        },
        "responses": { "200": { "description": "Upload URL" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/webhook-endpoints": {
      "get": {
        "summary": "List webhook endpoints",
        "operationId": "listWebhookEndpoints",
        "responses": { "200": { "description": "Endpoints" } },
        "security": [{ "apiKey": [] }]
      },
      "post": {
        "summary": "Create a webhook endpoint",
        "operationId": "createWebhookEndpoint",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": { "type": "string", "format": "uri" },
                  "eventTypes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "import.completed",
                        "import.rejected",
                        "job.completed",
                        "job.failed",
                        "job.canceled",
                        "job.expired",
                        "artifact.completed",
                        "artifact.failed"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Endpoint created; signing secret returned once" } },
        "security": [{ "apiKey": [] }]
      }
    },
    "/api/v1/webhook-endpoints/{endpointId}": {
      "delete": {
        "summary": "Delete a webhook endpoint",
        "operationId": "deleteWebhookEndpoint",
        "parameters": [
          { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "responses": { "200": { "description": "Deleted" } },
        "security": [{ "apiKey": [] }]
      }
    }
  },
  "components": {
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "schema": { "type": "string", "minLength": 1, "maxLength": 256 }
      }
    },
    "schemas": {
      "AssetPatchRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "name": { "type": "string", "minLength": 1, "maxLength": 120 },
          "featuredVersionId": { "type": "string" },
          "lastOpenedVersionId": { "type": "string" },
          "tags": { "type": "array", "maxItems": 12, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 32 } },
          "projectId": { "oneOf": [{ "type": "string" }, { "type": "null" }] }
        }
      },
      "VersionPatchRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "label": { "type": "string", "maxLength": 120 },
          "notes": { "type": "string", "maxLength": 2000 }
        }
      },
      "ProjectRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["name"],
        "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 } }
      },
      "BatchRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["intent", "files"],
        "properties": {
          "name": { "type": "string", "maxLength": 120 },
          "intent": { "type": "string", "enum": ["realistic", "stylized"] },
          "files": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["filename", "sizeBytes"],
              "properties": {
                "filename": { "type": "string", "minLength": 1, "maxLength": 255 },
                "sizeBytes": { "type": "integer", "minimum": 1 },
                "contentType": { "type": "string" },
                "sha256": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" }
              }
            }
          }
        }
      },
      "AppearanceInputRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["filename", "sizeBytes", "contentType"],
        "properties": {
          "filename": { "type": "string", "minLength": 1, "maxLength": 255 },
          "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 20971520 },
          "contentType": { "type": "string", "enum": ["image/png", "image/jpeg", "image/webp"] }
        }
      },
      "RetopoSettings": {
        "type": "object",
        "additionalProperties": false,
        "properties": { "targetQuadCount": { "type": "integer", "minimum": 4 } }
      },
      "CustomGenerationSettings": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": ["targetTriangleRatio"],
            "properties": {
              "targetTriangleRatio": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1 },
              "maxTextureSize": { "type": "integer", "minimum": 1 },
              "simplifyErrorBudget": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": ["targetTriangleCount"],
            "properties": {
              "targetTriangleCount": { "type": "integer", "minimum": 1 },
              "maxTextureSize": { "type": "integer", "minimum": 1 },
              "simplifyErrorBudget": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }
            }
          }
        ]
      },
      "PhysicalTransformSettings": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "rotationQuaternion": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "type": "number" } },
          "target": {
            "oneOf": [
              {
                "type": "object", "additionalProperties": false, "required": ["axis", "value", "unit"],
                "properties": {
                  "kind": { "type": "string", "enum": ["dimension"] },
                  "axis": { "type": "string", "enum": ["x", "y", "z", "max"] },
                  "value": { "type": "number", "exclusiveMinimum": 0 },
                  "unit": { "type": "string", "enum": ["m", "cm", "mm", "in"] }
                }
              },
              {
                "type": "object", "additionalProperties": false, "required": ["kind", "size", "unit"],
                "properties": {
                  "kind": { "type": "string", "enum": ["bounds"] },
                  "size": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": "number", "exclusiveMinimum": 0 } },
                  "unit": { "type": "string", "enum": ["m", "cm", "mm", "in"] }
                }
              },
              {
                "type": "object", "additionalProperties": false, "required": ["kind", "value", "unit"],
                "properties": {
                  "kind": { "type": "string", "enum": ["volume"] },
                  "value": { "type": "number", "exclusiveMinimum": 0 },
                  "unit": { "type": "string", "enum": ["m", "cm", "mm", "in"] }
                }
              }
            ]
          },
          "origin": { "type": "string", "enum": ["preserve", "center", "bottom-center"] },
          "ground": { "type": "boolean" }
        }
      },
      "PrintProfileSnapshot": {
        "type": "object",
        "required": ["process", "buildVolumeMm", "layerHeightMm", "minimumWallMm", "minimumFeatureMm", "partClearanceMm", "overhangThresholdDegrees", "practicalBridgeSpanMm"],
        "properties": {
          "process": { "type": "string", "enum": ["fdm", "resin"] },
          "buildVolumeMm": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": "number", "exclusiveMinimum": 0 } },
          "layerHeightMm": { "type": "number", "exclusiveMinimum": 0 },
          "nozzleDiameterMm": { "type": "number", "exclusiveMinimum": 0 },
          "perimeterCount": { "type": "integer", "minimum": 1 },
          "fdmProcessSettings": { "$ref": "#/components/schemas/FdmProcessSettings" },
          "pixelPitchMicrons": { "type": "number", "exclusiveMinimum": 0 },
          "exposureSeconds": { "type": "number", "exclusiveMinimum": 0 },
          "liftSeconds": { "type": "number", "exclusiveMinimum": 0 },
          "minimumWallMm": { "type": "number", "exclusiveMinimum": 0 },
          "minimumFeatureMm": { "type": "number", "exclusiveMinimum": 0 },
          "partClearanceMm": { "type": "number", "minimum": 0 },
          "overhangThresholdDegrees": { "type": "number", "minimum": 0, "maximum": 90 },
          "practicalBridgeSpanMm": { "type": "number", "minimum": 0 }
        }
      },
      "PrintPrepareSettings": {
        "type": "object",
        "additionalProperties": false,
        "required": ["printProfileId", "targetHeightMm", "automaticRepair"],
        "properties": {
          "printProfileId": { "type": "string", "minLength": 1 },
          "targetHeightMm": { "type": "number", "exclusiveMinimum": 0 },
          "automaticRepair": { "type": "boolean", "enum": [true] },
          "printProfileSnapshot": { "$ref": "#/components/schemas/PrintProfileSnapshot" }
        }
      },
      "FdmProcessSettings": {
        "type": "object", "additionalProperties": false,
        "properties": {
          "nozzleTemperatureC": { "type": "number", "minimum": 150, "maximum": 300 },
          "bedTemperatureC": { "type": "number", "minimum": 0, "maximum": 150 },
          "printSpeedMmPerS": { "type": "number", "minimum": 5, "maximum": 300 },
          "travelSpeedMmPerS": { "type": "number", "minimum": 10, "maximum": 500 },
          "retractionLengthMm": { "type": "number", "minimum": 0, "maximum": 15 },
          "retractionSpeedMmPerS": { "type": "number", "minimum": 5, "maximum": 120 }
        }
      },
      "PrintBaseTextSettings": {
        "type": "object",
        "additionalProperties": false,
        "required": ["text", "placement", "heightMm", "depthMm", "fontId"],
        "properties": {
          "text": { "type": "string", "minLength": 1 },
          "placement": { "type": "string", "enum": ["front-rim", "top-front", "underside"] },
          "heightMm": { "type": "number", "exclusiveMinimum": 0 },
          "depthMm": { "oneOf": [{ "type": "number", "exclusiveMinimum": 0 }, { "type": "number", "exclusiveMaximum": 0 }] },
          "fontId": { "type": "string", "enum": ["sans-standard"] }
        }
      },
      "PrintBaseSettings": {
        "oneOf": [
          {
            "type": "object", "additionalProperties": false, "required": ["shape", "diameterMm", "thicknessMm", "overlapMm"],
            "properties": {
              "shape": { "type": "string", "enum": ["round"] },
              "diameterMm": { "type": "number", "exclusiveMinimum": 0 },
              "thicknessMm": { "type": "number", "exclusiveMinimum": 0 },
              "overlapMm": { "type": "number", "minimum": 0 },
              "filletRadiusMm": { "type": "number", "minimum": 0 },
              "baseColor": { "type": "string" },
              "text": { "$ref": "#/components/schemas/PrintBaseTextSettings" }
            }
          },
          {
            "type": "object", "additionalProperties": false, "required": ["shape", "widthMm", "depthMm", "cornerRadiusMm", "thicknessMm", "overlapMm"],
            "properties": {
              "shape": { "type": "string", "enum": ["rounded-rectangle"] },
              "widthMm": { "type": "number", "exclusiveMinimum": 0 },
              "depthMm": { "type": "number", "exclusiveMinimum": 0 },
              "cornerRadiusMm": { "type": "number", "minimum": 0 },
              "thicknessMm": { "type": "number", "exclusiveMinimum": 0 },
              "overlapMm": { "type": "number", "minimum": 0 },
              "filletRadiusMm": { "type": "number", "minimum": 0 },
              "baseColor": { "type": "string" },
              "text": { "$ref": "#/components/schemas/PrintBaseTextSettings" }
            }
          }
        ]
      },
      "HollowSettings": {
        "type": "object",
        "additionalProperties": false,
        "required": ["wallThicknessMm", "drainHoleDiameterMm"],
        "properties": {
          "wallThicknessMm": { "type": "number", "exclusiveMinimum": 0 },
          "drainHoleDiameterMm": { "type": "number", "exclusiveMinimum": 0 },
          "drainPositionPercent": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number", "minimum": 0, "maximum": 100 } },
          "drainPositionsPercent": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "$ref": "#/components/schemas/PercentPair" } },
          "drainSurfacePointsMeters": {
            "type": "array", "minItems": 1, "maxItems": 3,
            "description": "Exact reviewed source-GLB surface points in model-space meters, in drain-position order.",
            "items": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": "number" } }
          },
          "drainDirection": { "type": "string", "enum": ["bottom", "top", "left", "right", "front", "back"] },
          "drainTiltPreset": { "type": "string", "enum": ["none", "u15", "u30", "v15", "v30"] },
          "drainTiltDegrees": {
            "type": "object", "additionalProperties": false, "required": ["u", "v"],
            "properties": { "u": { "type": "number", "minimum": -45, "maximum": 45 }, "v": { "type": "number", "minimum": -45, "maximum": 45 } }
          },
          "baseRegion": { "$ref": "#/components/schemas/HollowBand" },
          "wallRegions": { "type": "array", "maxItems": 3, "items": { "$ref": "#/components/schemas/HollowWallRegion" } },
          "interior": {
            "type": "object", "additionalProperties": false, "required": ["kind", "densityPercent"],
            "properties": {
              "kind": { "type": "string", "enum": ["gyroid", "rectilinear", "honeycomb"] },
              "densityPercent": { "type": "number", "minimum": 0, "maximum": 100 },
              "periodMm": { "type": "number", "exclusiveMinimum": 0 }
            }
          },
          "ballast": {
            "type": "object", "additionalProperties": false, "required": ["maxCavityFillPercent"],
            "properties": {
              "targetTippingAngleDegrees": { "type": "number", "exclusiveMinimum": 0 },
              "maxCavityFillPercent": { "type": "number", "minimum": 5, "maximum": 40 },
              "targetMassGrams": { "type": "number", "exclusiveMinimum": 0 },
              "densityGramsPerCm3": { "type": "number", "exclusiveMinimum": 0 }
            }
          },
          "fdmHollowAcknowledged": { "type": "boolean", "enum": [true] }
        }
      },
      "PercentPair": {
        "type": "array", "minItems": 2, "maxItems": 2,
        "items": { "type": "number", "minimum": 0, "maximum": 100 }
      },
      "HollowFill": {
        "oneOf": [
          { "type": "object", "additionalProperties": false, "required": ["kind"], "properties": { "kind": { "type": "string", "enum": ["solid"] } } },
          { "type": "object", "additionalProperties": false, "required": ["kind", "thicknessMm"], "properties": { "kind": { "type": "string", "enum": ["wall"] }, "thicknessMm": { "type": "number", "exclusiveMinimum": 0 } } }
        ]
      },
      "HollowBand": {
        "type": "object", "additionalProperties": false, "required": ["heightMm", "fill"],
        "properties": { "heightMm": { "type": "number", "exclusiveMinimum": 0 }, "fill": { "$ref": "#/components/schemas/HollowFill" } }
      },
      "HollowWallRegion": {
        "type": "object", "additionalProperties": false, "required": ["fromHeightMm", "toHeightMm", "fill"],
        "properties": { "fromHeightMm": { "type": "number", "minimum": 0 }, "toHeightMm": { "type": "number", "exclusiveMinimum": 0 }, "fill": { "$ref": "#/components/schemas/HollowFill" } }
      },
      "PrintSplitSettings": {
        "type": "object", "additionalProperties": false,
        "required": ["axis", "positionPercent", "connectorMode", "layoutMode"],
        "properties": {
          "axis": { "type": "string", "enum": ["x", "y", "z", "auto"] },
          "positionPercent": { "type": "number", "minimum": 0, "maximum": 100 },
          "cutPositionsPercent": { "type": "array", "items": { "type": "number", "minimum": 0, "maximum": 100 } },
          "connectorMode": { "type": "string", "enum": ["none", "peg-and-socket", "dual-peg", "keyed", "screw", "printed-screw"] },
          "layoutMode": { "type": "string", "enum": ["separated", "build-plate"] },
          "printProfileId": { "type": "string" },
          "printProfileSnapshot": { "$ref": "#/components/schemas/PrintProfileSnapshot" },
          "connectorClearanceMm": { "type": "number", "minimum": 0 },
          "maximumPartCount": { "type": "integer", "minimum": 2, "maximum": 12 },
          "cutNormal": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": "number" } },
          "cutFrameQuaternion": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "type": "number" } },
          "seamProfile": { "type": "string", "enum": ["flat", "stepped", "curved", "puzzle"] },
          "seamAmplitudeMm": { "type": "number", "minimum": 0.5, "maximum": 8 }
        }
      },
      "UnwrapSettings": {
        "type": "object", "additionalProperties": false, "required": ["layoutMode", "atlasSize", "marginPixels", "rebake"],
        "properties": {
          "layoutMode": { "type": "string", "enum": ["auto", "fixed"] },
          "atlasSize": { "type": "integer", "enum": [512, 1024, 2048, 4096] },
          "marginPixels": { "type": "integer", "minimum": 0 },
          "rebake": { "type": "string", "enum": ["auto", "always", "never"] }
        }
      },
      "AppearanceMaterialPatch": {
        "type": "object", "additionalProperties": false, "required": ["materialIndex"],
        "properties": {
          "materialIndex": { "type": "integer", "minimum": 0 },
          "baseColorFactor": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "type": "number", "minimum": 0, "maximum": 1 } },
          "metallicFactor": { "type": "number", "minimum": 0, "maximum": 1 },
          "roughnessFactor": { "type": "number", "minimum": 0, "maximum": 1 },
          "emissiveFactor": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": "number", "minimum": 0 } }
        }
      },
      "AppearanceEditSettings": {
        "oneOf": [
          { "type": "object", "additionalProperties": false, "required": ["operation", "patches"], "properties": { "operation": { "type": "string", "enum": ["material"] }, "patches": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/AppearanceMaterialPatch" } } } },
          { "type": "object", "additionalProperties": false, "required": ["operation", "maxTextureSize", "colorEncoding"], "properties": { "operation": { "type": "string", "enum": ["texture-optimize"] }, "maxTextureSize": { "type": "integer", "enum": [512, 1024, 2048, 4096] }, "colorEncoding": { "type": "string", "enum": ["preserve", "jpeg"] }, "jpegQuality": { "type": "integer", "minimum": 1, "maximum": 100 } } },
          { "type": "object", "additionalProperties": false, "required": ["operation", "materialIndex", "channel", "strokes"], "properties": { "operation": { "type": "string", "enum": ["paint"] }, "materialIndex": { "type": "integer", "minimum": 0 }, "channel": { "type": "string", "enum": ["base-color"] }, "strokes": { "type": "array", "items": { "$ref": "#/components/schemas/AppearancePaintStroke" } } } },
          { "type": "object", "additionalProperties": false, "required": ["operation", "materialIndex", "channel", "input"], "properties": { "operation": { "type": "string", "enum": ["channel-replace"] }, "materialIndex": { "type": "integer", "minimum": 0 }, "channel": { "type": "string", "enum": ["base-color", "normal", "metallic-roughness", "occlusion", "emissive"] }, "input": { "$ref": "#/components/schemas/AppearanceInput" } } }
        ]
      },
      "AppearancePaintStroke": {
        "type": "object", "additionalProperties": false, "required": ["points", "diameter", "hardness", "color"],
        "properties": {
          "points": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": ["u", "v"], "properties": { "u": { "type": "number", "minimum": 0, "maximum": 1 }, "v": { "type": "number", "minimum": 0, "maximum": 1 } } } },
          "diameter": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 },
          "hardness": { "type": "number", "minimum": 0, "maximum": 1 },
          "color": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "type": "number", "minimum": 0, "maximum": 1 } }
        }
      },
      "AppearanceInput": {
        "type": "object", "additionalProperties": false, "required": ["key", "filename", "contentType", "sizeBytes"],
        "properties": {
          "key": { "type": "string" }, "filename": { "type": "string" },
          "contentType": { "type": "string", "enum": ["image/png", "image/jpeg", "image/webp"] },
          "sizeBytes": { "type": "integer", "minimum": 1 }, "storageReservationId": { "type": "string" }
        }
      },
      "ActionCreditCosts": {
        "type": "object",
        "description": "Economy-v2 fixed credit costs. print_recipe is priced by its server-issued quote.",
        "required": ["economyVersion", "quick", "optimize", "retopo", "generate", "actions"],
        "properties": {
          "economyVersion": { "type": "integer", "enum": [2] },
          "quick": { "type": "integer", "minimum": 0 },
          "optimize": { "type": "integer", "minimum": 0 },
          "retopo": { "type": "integer", "minimum": 0 },
          "generate": { "type": "integer", "minimum": 0 },
          "actions": {
            "type": "object",
            "additionalProperties": { "oneOf": [{ "type": "integer", "minimum": 0 }, { "type": "string", "enum": ["quote"] }] }
          }
        },
        "example": {
          "economyVersion": 2,
          "quick": 1,
          "optimize": 5,
          "retopo": 15,
          "generate": 75,
          "actions": { "inspect": 0, "repair": 1, "optimize": 5, "retopo": 15, "generate": 75, "print_recipe": "quote" }
        }
      },
      "HumanoidRigSettings": {
        "type": "object", "additionalProperties": false, "required": ["profile", "bodyPlan", "landmarks", "maxInfluencesPerVertex"],
        "properties": {
          "profile": { "type": "string", "enum": ["messypoly-humanoid-v1", "messypoly-humanoid-v2"] },
          "bodyPlan": { "type": "string", "enum": ["humanoid"] },
          "landmarks": {
            "type": "object", "additionalProperties": false,
            "required": ["hips", "chest", "neck", "head", "leftShoulder", "leftElbow", "leftWrist", "rightShoulder", "rightElbow", "rightWrist", "leftHip", "leftKnee", "leftAnkle", "rightHip", "rightKnee", "rightAnkle"],
            "properties": {
              "hips": { "$ref": "#/components/schemas/Vec3" }, "chest": { "$ref": "#/components/schemas/Vec3" }, "neck": { "$ref": "#/components/schemas/Vec3" }, "head": { "$ref": "#/components/schemas/Vec3" },
              "leftShoulder": { "$ref": "#/components/schemas/Vec3" }, "leftElbow": { "$ref": "#/components/schemas/Vec3" }, "leftWrist": { "$ref": "#/components/schemas/Vec3" },
              "rightShoulder": { "$ref": "#/components/schemas/Vec3" }, "rightElbow": { "$ref": "#/components/schemas/Vec3" }, "rightWrist": { "$ref": "#/components/schemas/Vec3" },
              "leftHip": { "$ref": "#/components/schemas/Vec3" }, "leftKnee": { "$ref": "#/components/schemas/Vec3" }, "leftAnkle": { "$ref": "#/components/schemas/Vec3" },
              "rightHip": { "$ref": "#/components/schemas/Vec3" }, "rightKnee": { "$ref": "#/components/schemas/Vec3" }, "rightAnkle": { "$ref": "#/components/schemas/Vec3" }
            }
          },
          "maxInfluencesPerVertex": { "type": "integer", "enum": [4] }
        }
      },
      "Vec3": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": "number" } },
      "AnimationApplySettings": {
        "type": "object", "additionalProperties": false, "required": ["rigProfile", "clipIds"],
        "properties": {
          "rigProfile": { "type": "string", "enum": ["messypoly-humanoid-v1", "messypoly-humanoid-v2"] },
          "clipIds": { "type": "array", "minItems": 1, "maxItems": 4, "items": { "type": "string", "enum": ["idle-breathe", "idle", "walk-in-place", "run", "sit", "walk-start", "walk-stop", "look-around", "reach-interact", "turn-left-90", "turn-right-90", "crouch", "jump", "wave"] } },
          "boneMap": { "type": "object", "additionalProperties": { "type": "string" } }
        }
      },
      "GenerationSettings": {
        "type": "object", "additionalProperties": false,
        "properties": { "seed": { "type": "integer" }, "textureSize": { "type": "integer", "enum": [512, 1024, 2048] } }
      },
      "PrintRecipe": {
        "type": "object", "additionalProperties": false,
        "required": ["schemaVersion", "process", "preparationPresetId", "sizing", "fixes", "structural", "review"],
        "properties": {
          "schemaVersion": { "type": "integer", "enum": [1, 2] },
          "process": { "type": "string", "enum": ["fdm", "resin"] },
          "preparationPresetId": { "type": "string", "minLength": 1 },
          "preparationProfileSnapshot": { "$ref": "#/components/schemas/PrintProfileSnapshot" },
          "materialId": { "type": "string" },
          "sizing": {
            "type": "object", "additionalProperties": false, "required": ["kind", "axis", "value", "unit", "origin", "ground"],
            "properties": {
              "kind": { "type": "string", "enum": ["dimension"] }, "axis": { "type": "string", "enum": ["x", "y", "z", "max"] },
              "value": { "type": "number", "exclusiveMinimum": 0 }, "unit": { "type": "string", "enum": ["mm", "cm", "m", "in"] },
              "origin": { "type": "string", "enum": ["keep", "center", "bottom-center"] }, "ground": { "type": "boolean" }
            }
          },
          "fixes": {
            "type": "object", "additionalProperties": false, "required": ["automaticRepair", "fillReviewedOpenings", "rebuildAsSolid"],
            "properties": {
              "automaticRepair": { "type": "boolean", "enum": [true] }, "fillReviewedOpenings": { "type": "boolean" }, "rebuildAsSolid": { "type": "boolean" },
              "enlargeToMeetMinimums": { "type": "object", "additionalProperties": false, "required": ["maximumScale"], "properties": { "maximumScale": { "type": "number", "exclusiveMinimum": 1 } } },
              "thickenThinRegions": { "type": "boolean", "enum": [true] }
            }
          },
          "orientation": { "type": "object", "additionalProperties": false, "required": ["rotationQuaternion", "candidateId"], "properties": { "rotationQuaternion": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "type": "number" } }, "candidateId": { "type": "string" } } },
          "structural": {
            "oneOf": [
              { "type": "array", "items": { "$ref": "#/components/schemas/PrintStructuralStage" } },
              {
                "type": "object", "additionalProperties": false, "required": ["kind"],
                "properties": { "kind": { "type": "string", "enum": ["none", "base", "hollow", "split"] }, "settings": { "oneOf": [{ "$ref": "#/components/schemas/PrintBaseSettings" }, { "$ref": "#/components/schemas/HollowSettings" }, { "$ref": "#/components/schemas/PrintSplitSettings" }] } }
              }
            ]
          },
          "review": { "type": "object", "additionalProperties": false, "required": ["acceptedInspectionRevision", "acceptedAt"], "properties": { "acceptedInspectionRevision": { "type": "string" }, "acceptedAt": { "type": "string", "format": "date-time" }, "fdmHollowAcknowledged": { "type": "boolean", "enum": [true] } } }
        }
      },
      "PrintStructuralStage": {
        "oneOf": [
          { "type": "object", "required": ["kind", "settings"], "properties": { "kind": { "type": "string", "enum": ["hollow"] }, "settings": { "$ref": "#/components/schemas/HollowSettings" } } },
          { "type": "object", "required": ["kind", "settings"], "properties": { "kind": { "type": "string", "enum": ["split"] }, "settings": { "$ref": "#/components/schemas/PrintSplitSettings" } } },
          { "type": "object", "required": ["kind", "settings"], "properties": { "kind": { "type": "string", "enum": ["base"] }, "settings": { "$ref": "#/components/schemas/PrintBaseSettings" } } },
          { "type": "object", "required": ["kind", "settings"], "properties": { "kind": { "type": "string", "enum": ["supports"] }, "settings": { "$ref": "#/components/schemas/PrintSupportsSettings" } } }
        ]
      },
      "PrintSupportsSettings": {
        "type": "object", "additionalProperties": false, "required": ["tipDiameterMm", "bodyDiameterMm", "taperLengthMm", "process"],
        "properties": {
          "tipDiameterMm": { "type": "number", "minimum": 0.15, "maximum": 2 },
          "bodyDiameterMm": { "type": "number", "minimum": 0.15, "maximum": 6 },
          "taperLengthMm": { "type": "number", "minimum": 0.5, "maximum": 20 },
          "process": { "type": "string", "enum": ["resin"] }
        }
      },
      "PrintRecipeQuoteRequest": {
        "type": "object", "additionalProperties": false, "required": ["sourceVersionId", "recipe"],
        "properties": { "sourceVersionId": { "type": "string", "minLength": 1 }, "recipe": { "$ref": "#/components/schemas/PrintRecipe" } }
      },
      "ActionRequest": {
        "type": "object",
        "required": ["action"],
        "description": "Action-specific settings are validated by the referenced schemas. Fixed economy-v2 costs are published in info.x-action-credit-costs; print_recipe uses the server-issued quote.",
        "x-credit-costs": {
          "economyVersion": 2,
          "generate": 75,
          "optimize": 5,
          "retopo": 15,
          "quick": 1,
          "inspect": 0,
          "print_check": 0,
          "print_recipe": "quote"
        },
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "generate",
              "optimize",
              "retopo",
              "inspect",
              "repair",
              "fill_holes",
              "unwrap",
              "appearance",
              "resize",
              "add_base",
              "hollow",
              "print_prepare",
              "print_check",
              "print_recipe",
              "split",
              "rig",
              "animate"
            ]
          },
          "intent": {
            "type": "string",
            "enum": ["realistic", "stylized", "custom", "retopo"]
          },
          "custom": { "$ref": "#/components/schemas/CustomGenerationSettings" },
          "retopo": { "$ref": "#/components/schemas/RetopoSettings" },
          "resize": { "$ref": "#/components/schemas/PhysicalTransformSettings" },
          "printPrepare": { "$ref": "#/components/schemas/PrintPrepareSettings" },
          "printRecipe": { "$ref": "#/components/schemas/PrintRecipe" },
          "quoteId": { "type": "string" },
          "idempotencyKey": { "type": "string", "description": "Print-recipe quote claim key (separate from Idempotency-Key header)" },
          "base": { "$ref": "#/components/schemas/PrintBaseSettings" },
          "hollow": { "$ref": "#/components/schemas/HollowSettings" },
          "split": { "$ref": "#/components/schemas/PrintSplitSettings" },
          "unwrap": { "$ref": "#/components/schemas/UnwrapSettings" },
          "appearance": { "$ref": "#/components/schemas/AppearanceEditSettings" },
          "rig": { "$ref": "#/components/schemas/HumanoidRigSettings" },
          "animation": { "$ref": "#/components/schemas/AnimationApplySettings" },
          "generation": { "$ref": "#/components/schemas/GenerationSettings" }
        }
      }
    },
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "mpk"
      }
    }
  }
}