{
  "openapi": "3.1.0",
  "info": {
    "title": "CleanBurn AI — Powered by Phoenix (Public Free Playground API)",
    "version": "1.4.0",
    "description": "Read-only, Clean-Air-compliant vehicle combustion physics analyzer and 6-parameter ECU tune safety preview API. Versioning policy: /api/v1/ endpoints carry a minimum 90-day Deprecation and Sunset header notice prior to any breaking change.",
    "contact": {
      "name": "CleanBurn AI Engineering",
      "email": "support@cleanburn.ai",
      "url": "https://cleanburn-ai-phoenix.netlify.app/docs/"
    }
  },
  "servers": [
    {
      "url": "https://cleanburn-ai-phoenix.netlify.app",
      "description": "Production HTTPS Server"
    }
  ],
  "components": {
    "schemas": {
      "ApiError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "code": {
            "type": "string",
            "example": "PII_VIN_DETECTED"
          },
          "error": {
            "type": "string",
            "example": "Payload rejected: unstripped 17-character VIN detected."
          },
          "resolution": {
            "type": "string",
            "example": "Strip 17-character VIN strings locally before calling the API."
          }
        }
      },
      "PhysicsVector": {
        "type": "object",
        "properties": {
          "sample_rows": {
            "type": "integer",
            "example": 3200
          },
          "rpm_max": {
            "type": "number",
            "example": 6200
          },
          "map_kpa_max": {
            "type": "number",
            "example": 185
          },
          "lambda_wot": {
            "type": "number",
            "example": 0.83
          },
          "stft_b1_avg": {
            "type": "number",
            "example": 1.2
          },
          "ltft_b1_avg": {
            "type": "number",
            "example": 2.4
          },
          "idle_trim_pct": {
            "type": "number",
            "example": 12.8
          },
          "cruise_trim_pct": {
            "type": "number",
            "example": 2.1
          },
          "kr_deg_max": {
            "type": "number",
            "example": 0
          },
          "rail_psi_min_load": {
            "type": "number",
            "example": 2100
          },
          "ipw_ms_max": {
            "type": "number",
            "example": 5.1
          }
        }
      },
      "StatusResponse": {
        "type": "object",
        "required": [
          "service",
          "status",
          "compliance_mode"
        ],
        "properties": {
          "service": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "ONLINE"
            ]
          },
          "premium_fulfillment_mode": {
            "type": "string",
            "enum": [
              "WAITLIST_HOLD",
              "LIVE"
            ]
          },
          "compliance_mode": {
            "type": "string"
          },
          "free_tools_enabled": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "FreeScanResponse": {
        "type": "object",
        "required": [
          "engine_rebirth_score",
          "smog_readiness_outlook",
          "guided_rebirth_plan"
        ],
        "properties": {
          "mentor_name": {
            "type": "string"
          },
          "mentor_summary": {
            "type": "string"
          },
          "engine_rebirth_score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "smog_readiness_outlook": {
            "type": "string"
          },
          "guided_rebirth_plan": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "severity": {
                  "type": "string"
                },
                "what": {
                  "type": "string"
                },
                "why_the_hips": {
                  "type": "string"
                },
                "when": {
                  "type": "string"
                },
                "how": {
                  "type": "string"
                },
                "who": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "FreeTuneResponse": {
        "type": "object",
        "required": [
          "ok",
          "overall_grade",
          "overall_score",
          "safety_verdict",
          "parameter_grades"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "playground_mode": {
            "type": "string"
          },
          "overall_grade": {
            "type": "string",
            "enum": [
              "A",
              "B",
              "C",
              "D",
              "F"
            ]
          },
          "overall_score": {
            "type": "integer"
          },
          "critical_safety_cap_triggered": {
            "type": "boolean"
          },
          "safety_verdict": {
            "type": "string"
          },
          "parameter_grades": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "parameter": {
                  "type": "string"
                },
                "score": {
                  "type": "integer"
                },
                "grade": {
                  "type": "string"
                },
                "unlocked_in_free_tier": {
                  "type": "boolean"
                },
                "measured": {
                  "type": "string"
                },
                "the_hips": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "FreePreflightResponse": {
        "type": "object",
        "required": [
          "ok",
          "ticket_status",
          "preflight_blockers"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "ticket_status": {
            "type": "string",
            "enum": [
              "PREFLIGHT_MECHANICAL_HOLD",
              "NEEDS_SETUP_CLARIFICATION",
              "STAGED_FOR_MASTER"
            ]
          },
          "preflight_blockers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pending_questions_remaining": {
            "type": "integer"
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/status": {
      "get": {
        "operationId": "getSystemStatus",
        "summary": "Retrieve service health, compliance mode, and active free tools",
        "description": "Returns operational status, Clean-Air compliance mode, and enabled free diagnostic tools.",
        "responses": {
          "200": {
            "description": "System status JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "422": {
            "description": "Clean-Air or Zero-PII validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (see Retry-After header)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/phoenix/free-scan": {
      "post": {
        "operationId": "runFreeCombustionScan",
        "summary": "Run a free anonymized engine rebirth & fuel-trim/knock diagnostic scan",
        "description": "Evaluates STFT/LTFT fuel trims, idle vs. cruise trim split, knock retard, battery voltage, and GDI rail pressure to produce a step-by-step Rebirth Plan.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "physics_vector"
                ],
                "properties": {
                  "engine_family_bucket": {
                    "type": "string",
                    "example": "GM_GENV_V8_E92"
                  },
                  "user_symptom_note": {
                    "type": "string",
                    "example": "Rough warm idle"
                  },
                  "physics_vector": {
                    "$ref": "#/components/schemas/PhysicsVector"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rebirth score and step-by-step root-cause plan",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeScanResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "422": {
            "description": "Clean-Air or Zero-PII validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (see Retry-After header)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/phoenix/free-tune-playground": {
      "post": {
        "operationId": "runFreeTuneSafetyPlayground",
        "summary": "Grade an ECU calibration A-F on WOT AFR, Knock, Trims, Rail Pressure, Drivetrain & Readiness",
        "description": "Enforces a hard safety override on lean boosted WOT (>0.90 Lambda), >5.0 deg knock retard, or <900 psi GDI rail pressure while omitting third-party shop names.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "telemetry"
                ],
                "properties": {
                  "engine_family_bucket": {
                    "type": "string",
                    "example": "GM_GENV_V8_E92"
                  },
                  "is_boosted": {
                    "type": "boolean",
                    "example": true
                  },
                  "customer_context": {
                    "type": "string",
                    "example": "91 octane street pull"
                  },
                  "telemetry": {
                    "$ref": "#/components/schemas/PhysicsVector"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Free tune safety grade preview",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeTuneResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "422": {
            "description": "Clean-Air or Zero-PII validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (see Retry-After header)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/master/free-preflight": {
      "post": {
        "operationId": "runFreeMasterPreflight",
        "summary": "Simulate mechanical pre-flight and 1-at-a-time part setup quality interrogation",
        "description": "Checks mechanical health blockers and interrogates ambiguous fuel octane, injector characterization, or MAP sensor details one question at a time.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "physics_vector",
                  "build_sheet"
                ],
                "properties": {
                  "engine_family_bucket": {
                    "type": "string",
                    "example": "GM_GENV_V8_E92"
                  },
                  "physics_vector": {
                    "$ref": "#/components/schemas/PhysicsVector"
                  },
                  "build_sheet": {
                    "type": "object"
                  },
                  "clarifications": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Pre-flight status and next setup question",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreePreflightResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "422": {
            "description": "Clean-Air or Zero-PII validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (see Retry-After header)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    }
  }
}
