{
  "openapi": "3.1.0",
  "info": {
    "title": "Skinflint Regret Tax API",
    "version": "2026-07-19",
    "description": "Deterministic, source-dated e-bike return eligibility and known exit-cost estimates for U.S. direct orders. Unknown freight is never treated as zero."
  },
  "servers": [
    {
      "url": "https://skinflint.ai"
    }
  ],
  "externalDocs": {
    "description": "Agent integration notes and public feed terms",
    "url": "https://skinflint.ai/developers/"
  },
  "paths": {
    "/api/estimate": {
      "get": {
        "operationId": "estimateEbikeReturnExitCost",
        "summary": "Estimate known e-bike return costs",
        "description": "Returns a deterministic estimate backed by Skinflint's dated policy record. This is a pre-purchase summary, not legal advice; confirm the first-party policy at checkout.",
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "lectric",
                "aventon",
                "velotric",
                "rad-power-bikes",
                "ride1up-revv1",
                "fiido",
                "himiway",
                "hovsco",
                "ecotric",
                "engwe",
                "gotrax",
                "tenways",
                "segway-o2o-ebike"
              ]
            },
            "description": "Skinflint brand record identifier."
          },
          {
            "name": "price",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number",
              "minimum": 200,
              "maximum": 15000
            },
            "description": "Bike price in USD."
          },
          {
            "name": "condition",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "unopened",
                "ridden"
              ],
              "default": "ridden"
            },
            "description": "Return condition to evaluate."
          }
        ],
        "responses": {
          "200": {
            "description": "Source-dated policy and exit-cost estimate.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EstimateResponse"
                },
                "examples": {
                  "aventonRidden": {
                    "summary": "A $1,500 ridden Aventon",
                    "value": {
                      "request": {
                        "brand": "aventon",
                        "price": 1500,
                        "condition": "ridden",
                        "currency": "USD"
                      },
                      "estimate": {
                        "eligible": true,
                        "knownExitCostMin": 875,
                        "knownExitCostMax": 875,
                        "estimatedRefundMin": 625,
                        "estimatedRefundMax": 625,
                        "currency": "USD"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid query parameter."
          },
          "404": {
            "description": "Unknown brand record."
          },
          "405": {
            "description": "Method not allowed."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EstimateResponse": {
        "type": "object",
        "required": [
          "apiVersion",
          "request",
          "policy",
          "estimate",
          "links"
        ],
        "properties": {
          "apiVersion": {
            "type": "string",
            "format": "date"
          },
          "request": {
            "type": "object"
          },
          "policy": {
            "type": "object",
            "description": "Normalized policy facts with first-party source and checked date."
          },
          "estimate": {
            "type": "object",
            "description": "Known exit-cost range, estimated refund range, risk, and caveats."
          },
          "links": {
            "type": "object",
            "description": "Canonical calculator, human breakdown, first-party source, documentation, and optional paid guide/watch."
          }
        }
      }
    }
  }
}