Skip to content

COVEROQ CAD API Documentation (.NET 10 Minimal APIs)

Welcome to the public API documentation for the COVEROQ CAD Platform C# .NET 10 backend.

🔗 Interactive OpenAPI / Swagger UI

An interactive OpenAPI specification and Swagger UI runner is built directly into the C# backend API server:

Using Swagger UI, administrators and storefront developers can inspect request/response schemas, test endpoints live, and pass the administrative authorization token.

🔐 Authentication & Authorization Schemes

The COVEROQ CAD API uses a dual access model:

  1. Public / Storefront Endpoints: Accessible anonymously without tokens, protected by CORS policy AllowStorefrontEmbed and HMAC token signing for e-commerce security.
  2. Administrative Endpoints (/api/admin/*, /api/logs, /api/traces, /api/tests/*): Secured by the AdminOnly policy handled by AdminTokenAuthHandler.
  3. Administrative endpoints require passing a secret token via either:
    • Header: X-Admin-Token: <token>
    • Header: Authorization: Bearer <token>

📋 API Endpoint Contracts

1. Health & System Diagnostics

GET /api/health

  • Summary: Check system health status.
  • Auth: Public
  • Description: Verifies database connectivity, active CAD worker gateway SignalR connection (/hubs/cad), and deployment version metadata.
  • Response (200 OK): json { "status": "healthy", "database": "online", "cad_worker": "online", "version": { "release": "1.0.0", "built_at": "2026-09-29T12:00:00Z", "runtime": ".NET 10 (C# 10+)", "status": "online" } }

2. Models & Inspection

GET /api/models

  • Summary: List available model templates.
  • Auth: Public
  • Description: Fetches all active parametric CAD model templates and parts in the catalog.

POST /api/models/inspect

  • Summary: Inspect CAD model file (.FCStd).
  • Auth: Admin (X-Admin-Token)
  • Description: Uploads a .FCStd CAD document to the worker via SignalR CadHub for headless inspection of the Vars spreadsheet table, parameters, bounds, GLB preview generation, and LCS anchor points.

POST /api/models/confirm

  • Summary: Confirm model template import.
  • Auth: Admin (X-Admin-Token)
  • Description: Confirms and persists model template metadata, parameters, and 3D thumbnail Base64 in the database.

3. Orders & Parametric Model Configuration

POST /api/orders/configure

  • Summary: Configure CAD model parameters.
  • Auth: Public
  • Description: Accepts user-selected parametric dimensions for a furniture model template, checks parameter bounds, and dispatches a 3D geometry generation job to the CAD worker gateway via SignalR CadHub.

GET /api/orders/{orderId}

  • Summary: Get CAD order status and file links.
  • Auth: Public
  • Description: Queries the current status of a CAD generation order and retrieves URLs for generated GLB and STEP artifacts.

4. CAD Assembly Management (Studio)

GET /api/admin/assembly/{id}/tree

  • Summary: Get assembly component tree.
  • Auth: Admin (X-Admin-Token)
  • Description: Retrieves the structural assembly hierarchy, master skeleton parameters, LCS (Local Coordinate System) anchor points, assigned child parts, and parameter bindings.

POST /api/admin/assembly/{id}/swap

  • Summary: Swap assembly component.
  • Auth: Admin (X-Admin-Token)
  • Description: Swaps or assigns a replacement child part to a specific LCS anchor point inside an assembly.

POST /api/admin/assembly/{id}/recompute

  • Summary: Recompute assembly skeleton parameters.
  • Auth: Admin (X-Admin-Token)
  • Description: Recomputes parametric skeleton expressions and updates LCS anchor coordinates across all assembly child components.

5. Distributed Tracing & Causality Queries

GET /api/traces

  • Summary: List recent execution traces.
  • Auth: Admin (X-Admin-Token)
  • Description: Retrieves paginated root execution traces with total duration, span counts, and status filters.

GET /api/traces/{traceId}

  • Summary: Get trace execution DAG graph.
  • Auth: Admin (X-Admin-Token)
  • Description: Fetches the full Directed Acyclic Graph (DAG) tree data for a specific operation trace ID.

6. Diagnostics, Telemetry & SignalR Hubs

POST /api/log

  • Summary: Ingest client telemetry log event.
  • Auth: Public
  • Description: Ingests client-side logging events into backend Serilog sink.

GET /api/logs

  • Summary: Get diagnostic logs.
  • Auth: Admin (X-Admin-Token)
  • Query Parameters: lines (default: 100), exceptions_only, search, source, level.

SignalR Hub: /hubs/cad

  • Protocol: WebSockets / SignalR
  • Description: Persistent bidirectional connection for CAD worker registration (RegisterWorker), job progress reports (ReportJobProgress), job completions (ReportJobCompleted), and telemetry log dispatches.

SignalR Hub: /hubs/telemetry

  • Protocol: WebSockets / SignalR
  • Description: Real-time log streaming (ReceiveLog), trace updates (OnTraceSpanUpdated), and worker status broadcasts (WorkerStatusChanged).

🌐 Web Application & Static Content Routes

  • / -> Serves Web Hub (hub.html).
  • /studio -> Serves CAD Product Studio UI (studio.html).
  • /inspector -> Serves Model Inspector UI (inspector.html).
  • /models -> Serves Model Management UI (models.html).
  • /logs -> Serves Diagnostic Streaming & DAG UI (logs.html).
  • /storage/{filepath} -> Serves 3D GLB, STEP, DXF, SVG, and WebP model files with proper MIME types.