{
  "openapi": "3.0.4",
  "info": {
    "title": "Coveroq CAD API",
    "description": "Core parametric 3D CAD platform API for skeleton assembly configuration, 6-DOF LCS solving, GLB mesh previews, and worker telemetry.",
    "version": "v1"
  },
  "paths": {
    "/api/assembly/{id}/tree": {
      "get": {
        "tags": [
          "Assembly"
        ],
        "summary": "Get assembly component tree",
        "description": "Retrieves the full structural assembly component tree and LCS anchor points.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/assembly/{id}/swap": {
      "post": {
        "tags": [
          "Assembly"
        ],
        "summary": "Swap assembly component",
        "description": "Swaps a child component at a specified LCS anchor point within an assembly.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SwapAssemblyComponentCommand"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/assembly/{id}/recompute": {
      "post": {
        "tags": [
          "Assembly"
        ],
        "summary": "Recompute assembly skeleton",
        "description": "Recomputes parametric skeleton dimensions for an assembly model.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecomputeAssemblySkeletonCommand"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/admin/assembly/{id}/tree": {
      "get": {
        "tags": [
          "Assembly"
        ],
        "summary": "Get assembly component tree",
        "description": "Retrieves the full structural assembly component tree and LCS anchor points.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/admin/assembly/{id}/swap": {
      "post": {
        "tags": [
          "Assembly"
        ],
        "summary": "Swap assembly component",
        "description": "Swaps a child component at a specified LCS anchor point within an assembly.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SwapAssemblyComponentCommand"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/admin/assembly/{id}/recompute": {
      "post": {
        "tags": [
          "Assembly"
        ],
        "summary": "Recompute admin assembly skeleton",
        "description": "Recomputes parametric skeleton dimensions for an administrative assembly model.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecomputeAssemblySkeletonCommand"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/assemblies/{skeletonId}/configurations": {
      "post": {
        "tags": [
          "Assembly"
        ],
        "summary": "Save structural assembly configuration",
        "description": "Persists a named part placement configuration for a skeleton.",
        "parameters": [
          {
            "name": "skeletonId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SaveAssemblyConfigurationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "get": {
        "tags": [
          "Assembly"
        ],
        "summary": "Get assembly configurations by skeleton",
        "description": "Retrieves all saved structural configurations for a specified skeleton.",
        "parameters": [
          {
            "name": "skeletonId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/assemblies/configurations/{id}": {
      "get": {
        "tags": [
          "Assembly"
        ],
        "summary": "Get assembly configuration by ID",
        "description": "Retrieves a single structural assembly configuration with its axis part assignments.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "delete": {
        "tags": [
          "Assembly"
        ],
        "summary": "Delete assembly configuration",
        "description": "Deletes a saved structural assembly configuration.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/auth/validate": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Validate administrative secret token",
        "description": "Returns HTTP 200 with admin role if the provided admin token is valid, or HTTP 401 if unauthorized.",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/logs": {
      "get": {
        "tags": [
          "Diagnostics"
        ],
        "summary": "Get diagnostic logs",
        "description": "Retrieves diagnostic backend log events filtered by level, source, or search term.",
        "parameters": [
          {
            "name": "lines",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 100
            }
          },
          {
            "name": "exceptions_only",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "level",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/tests/run": {
      "post": {
        "tags": [
          "Diagnostics"
        ],
        "summary": "Run backend diagnostics",
        "description": "Executes database, CAD worker gateway, and file storage diagnostic checks.",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "tags": [
          "Health"
        ],
        "summary": "Check system health status",
        "description": "Returns the health status of database, CAD worker gateway, and runtime environment.",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/version": {
      "get": {
        "tags": [
          "Health"
        ],
        "summary": "Get deployment version metadata",
        "description": "Returns git commit, tag, and build timestamp from assembly metadata.",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/models": {
      "get": {
        "tags": [
          "Models"
        ],
        "summary": "List model templates",
        "description": "Returns all registered CAD model templates.",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/models/{modelId}/parameters": {
      "get": {
        "tags": [
          "Models"
        ],
        "summary": "Get model template parameters",
        "description": "Retrieves available parameters and ranges for a specific model template.",
        "parameters": [
          {
            "name": "modelId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "put": {
        "tags": [
          "Models"
        ],
        "summary": "Update model parameters",
        "description": "Updates allowable bounds, labels, and default values for model template parameters.",
        "parameters": [
          {
            "name": "modelId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ModelParameterDto"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/models/inspect": {
      "post": {
        "tags": [
          "Models"
        ],
        "summary": "Inspect uploaded CAD model file",
        "description": "Uploads and inspects a .fcstd CAD model file on the worker, returning extracted parameters and suggested template metadata.",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "required": [
                  "file"
                ],
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              },
              "encoding": {
                "file": {
                  "style": "form"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/models/confirm": {
      "post": {
        "tags": [
          "Models"
        ],
        "summary": "Confirm model import",
        "description": "Confirms import of a staged CAD model file and registers it as a permanent model template with parameters.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConfirmModelImportCommand"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/models/{modelId}": {
      "delete": {
        "tags": [
          "Models"
        ],
        "summary": "Delete model template",
        "description": "Deletes a model template, its associated parameters, and physical CAD storage files.",
        "parameters": [
          {
            "name": "modelId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/models/{modelId}/template": {
      "get": {
        "tags": [
          "Models"
        ],
        "summary": "Download model template file",
        "description": "Retrieves the physical .fcstd CAD model template file.",
        "parameters": [
          {
            "name": "modelId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/models/{modelId}/thumbnail": {
      "get": {
        "tags": [
          "Models"
        ],
        "summary": "Get model thumbnail image",
        "description": "Retrieves the thumbnail image for a specific model template.",
        "parameters": [
          {
            "name": "modelId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/workers/jobs/{jobId}/artifacts": {
      "post": {
        "tags": [
          "Workers"
        ],
        "summary": "Upload worker job artifact",
        "description": "Uploads a preview mesh (.glb) or thumbnail generated by the CAD worker.",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "required": [
                  "file"
                ],
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              },
              "encoding": {
                "file": {
                  "style": "form"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ConfirmModelImportCommand": {
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/ModelType"
          },
          "parameters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ModelParameterDto"
            },
            "nullable": true
          },
          "lcsPoints": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LcsPointDto"
            },
            "nullable": true
          },
          "spreadsheetName": {
            "type": "string",
            "nullable": true
          },
          "tempToken": {
            "type": "string",
            "nullable": true
          },
          "modelId": {
            "type": "string",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "thumbnailBase64": {
            "type": "string",
            "nullable": true
          },
          "thumbnailUrl": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "LcsPointDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "position": {
            "type": "array",
            "items": {
              "type": "number",
              "format": "double"
            },
            "nullable": true
          },
          "rotation": {
            "type": "array",
            "items": {
              "type": "number",
              "format": "double"
            },
            "nullable": true
          },
          "socketType": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "ModelParameterDto": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "nullable": true
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "defaultValue": {
            "type": "number",
            "format": "double"
          },
          "minValue": {
            "type": "number",
            "format": "double"
          },
          "maxValue": {
            "type": "number",
            "format": "double"
          },
          "stepValue": {
            "type": "number",
            "format": "double"
          },
          "isVisible": {
            "type": "boolean"
          },
          "unit": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "ModelType": {
        "enum": [
          0,
          1
        ],
        "type": "integer",
        "format": "int32"
      },
      "RecomputeAssemblySkeletonCommand": {
        "type": "object",
        "properties": {
          "assemblyId": {
            "type": "string",
            "nullable": true
          },
          "parameters": {
            "type": "object",
            "additionalProperties": {
              "type": "number",
              "format": "double"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "SaveAssemblyConfigurationRequest": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "slots": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "SwapAssemblyComponentCommand": {
        "type": "object",
        "properties": {
          "assemblyId": {
            "type": "string",
            "nullable": true
          },
          "lcsName": {
            "type": "string",
            "nullable": true
          },
          "newPartId": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "X-Admin-Token": {
        "type": "apiKey",
        "description": "Administrative secret token required for admin operations.",
        "name": "X-Admin-Token",
        "in": "header"
      }
    }
  },
  "security": [
    { }
  ],
  "tags": [
    {
      "name": "Assembly"
    },
    {
      "name": "Authentication"
    },
    {
      "name": "Diagnostics"
    },
    {
      "name": "Health"
    },
    {
      "name": "Models"
    },
    {
      "name": "Workers"
    }
  ]
}