{
  "openapi": "3.1.0",
  "info": {
    "title": "NextCast Engineering API",
    "version": "1.0.0",
    "description": "Public API for NextCast Engineering — industrieller Metall-3D-Druck (SLM). Materialberatung, Machbarkeitsprüfung und automatisierte Qualitätsanalyse."
  },
  "servers": [
    {
      "url": "https://nextcast-engineering.de",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/v1/materials": {
      "get": {
        "operationId": "listMaterials",
        "summary": "Verfügbare SLM-Materialien abrufen",
        "description": "Returns all active materials with their properties, wall thickness thresholds, and pricing. No authentication required.",
        "responses": {
          "200": {
            "description": "Material list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "materials": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Material" }
                    },
                    "count": { "type": "integer" }
                  }
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/check-feasibility": {
      "post": {
        "operationId": "checkFeasibility",
        "summary": "Schnelle Machbarkeitsprüfung",
        "description": "Quick feasibility check based on material, dimensions, and wall thickness. Returns pass/review/fail verdict with reasoning. No file upload or authentication needed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/FeasibilityRequest" },
              "example": {
                "material": "316L",
                "dimensions_mm": { "x": 80, "y": 40, "z": 30 },
                "wall_thickness_mm": 0.6
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Feasibility verdict",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/FeasibilityResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "404": {
            "description": "Material not found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/analyze": {
      "post": {
        "operationId": "analyzeFile",
        "summary": "STL/STEP-Datei analysieren (AQA)",
        "description": "Upload an STL or STEP file for full automated quality analysis (AQA). Requires API key authentication. The analysis may take up to 60 seconds. If the analysis is not complete within 60 seconds, a 202 response is returned with an analysis_id for polling.",
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file", "material"],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "STL, STEP, or STP file (max 50MB)"
                  },
                  "material": {
                    "type": "string",
                    "description": "Material key (e.g. '316L', 'AlSi10Mg', 'Ti6Al4V', 'IN718', 'MS1')"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Analysis complete",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AnalysisResponse" }
              }
            }
          },
          "202": {
            "description": "Analysis still processing — poll GET /api/v1/analyze/{id}",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AnalysisResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/analyze/{id}": {
      "get": {
        "operationId": "getAnalysis",
        "summary": "Analyseergebnis abrufen",
        "description": "Poll for analysis results by ID. Requires the same API key used to create the analysis.",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" },
            "description": "Analysis ID returned from POST /api/v1/analyze"
          }
        ],
        "responses": {
          "200": {
            "description": "Analysis result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AnalysisResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": {
            "description": "Analysis not found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key starting with nc_. Generate at https://nextcast-engineering.de/dashboard/settings"
      }
    },
    "schemas": {
      "Material": {
        "type": "object",
        "properties": {
          "key": { "type": "string", "example": "316L" },
          "name": { "type": "string", "example": "316L (1.4404)" },
          "category": { "type": "string", "example": "Edelstahl" },
          "density_g_per_cm3": { "type": "number", "example": 7.99 },
          "wall_thickness": {
            "type": "object",
            "properties": {
              "hard_fail_mm": { "type": "number", "example": 0.3 },
              "review_zone_mm": { "type": "number", "example": 0.5 },
              "green_light_mm": { "type": "number", "example": 0.5 }
            }
          },
          "min_detail_mm": { "type": "number" },
          "critical_overhang_deg": { "type": "number", "nullable": true },
          "cost_per_kg_eur": { "type": "number" },
          "description": { "type": "string" }
        }
      },
      "FeasibilityRequest": {
        "type": "object",
        "required": ["material", "dimensions_mm", "wall_thickness_mm"],
        "properties": {
          "material": {
            "type": "string",
            "description": "Material key (e.g. '316L', 'AlSi10Mg')"
          },
          "dimensions_mm": {
            "type": "object",
            "required": ["x", "y", "z"],
            "properties": {
              "x": { "type": "number", "description": "Length in mm" },
              "y": { "type": "number", "description": "Width in mm" },
              "z": { "type": "number", "description": "Height in mm" }
            }
          },
          "wall_thickness_mm": {
            "type": "number",
            "description": "Minimum wall thickness in mm"
          }
        }
      },
      "FeasibilityResponse": {
        "type": "object",
        "properties": {
          "feasibility": {
            "type": "string",
            "enum": ["pass", "review", "fail"],
            "description": "pass = druckbar, review = Ingenieur-Prüfung, fail = nicht machbar"
          },
          "reason": { "type": "string" },
          "material": { "type": "string" },
          "thresholds": {
            "type": "object",
            "properties": {
              "hard_fail_mm": { "type": "number" },
              "review_zone_mm": { "type": "number" },
              "green_light_mm": { "type": "number" }
            }
          },
          "bounding_box_ok": { "type": "boolean" },
          "max_build_volume_mm": {
            "type": "object",
            "properties": {
              "x": { "type": "number" },
              "y": { "type": "number" },
              "z": { "type": "number" }
            }
          }
        }
      },
      "AnalysisResponse": {
        "type": "object",
        "properties": {
          "analysis_id": { "type": "string", "format": "uuid" },
          "status": { "type": "string", "example": "passed" },
          "aqa_report": {
            "type": "object",
            "description": "Full AQA report with mesh validation, bounding box, wall thickness analysis"
          },
          "material": { "type": "string" },
          "file_name": { "type": "string" },
          "message": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    }
  }
}