{
  "openapi": "3.0.3",
  "info": {
    "title": "Car Finance Refund Tool - public API",
    "version": "1.1.0",
    "description": "Agent-friendly public API for discovering the Car Finance Refund Tool, reading live pricing/lender metadata, and calculating illustrative DCA refund estimates. The complaint letter generator is available via the HTML flow at /letter and the markdown guide at /letter.md. Not legal or financial advice.",
    "termsOfService": "https://carfinancerefundletter.co.uk/terms",
    "contact": {
      "name": "The Car Finance Refund Team",
      "url": "https://carfinancerefundletter.co.uk/about"
    }
  },
  "externalDocs": {
    "description": "LLM and agent navigation file",
    "url": "https://carfinancerefundletter.co.uk/llms.txt"
  },
  "servers": [
    {
      "url": "https://carfinancerefundletter.co.uk/api",
      "description": "Production via Firebase Hosting rewrite"
    }
  ],
  "tags": [
    {
      "name": "Discovery",
      "description": "Endpoints that help agents identify, cite, and route users to the correct tool."
    },
    {
      "name": "Calculator",
      "description": "Illustrative DCA refund calculation."
    },
    {
      "name": "Reference",
      "description": "Read-only pricing and lender metadata."
    }
  ],
  "paths": {
    "/agent-info": {
      "get": {
        "tags": ["Discovery"],
        "operationId": "getAgentInfo",
        "summary": "Agent discovery metadata",
        "description": "Returns canonical URLs, markdown companions, API docs, tool routing guidance, trust signals, and disclaimers for AI agents.",
        "responses": {
          "200": {
            "description": "Agent discovery metadata",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentInfo" },
                "examples": {
                  "default": {
                    "value": {
                      "service": "car-finance-refund-tool",
                      "name": "Car Finance Refund Tool",
                      "canonicalUrl": "https://carfinancerefundletter.co.uk/",
                      "llmsTxt": "https://carfinancerefundletter.co.uk/llms.txt",
                      "openapi": "https://carfinancerefundletter.co.uk/openapi.json",
                      "tools": [
                        {
                          "id": "dca-refund-calculator",
                          "name": "DCA car finance refund calculator",
                          "uiUrl": "https://carfinancerefundletter.co.uk/calculator",
                          "markdownUrl": "https://carfinancerefundletter.co.uk/calculator.md",
                          "api": {
                            "method": "POST",
                            "url": "https://carfinancerefundletter.co.uk/api/calculate-dca-refund"
                          }
                        },
                        {
                          "id": "complaint-letter-generator",
                          "name": "Motor finance complaint letter generator",
                          "uiUrl": "https://carfinancerefundletter.co.uk/letter",
                          "markdownUrl": "https://carfinancerefundletter.co.uk/letter.md"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": ["Discovery"],
        "operationId": "getHealth",
        "summary": "Service health",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HealthResponse" },
                "examples": {
                  "ok": {
                    "value": {
                      "status": "ok",
                      "service": "car-finance-refund-tool-api",
                      "time": "2026-05-16T14:58:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/pricing": {
      "get": {
        "tags": ["Reference"],
        "operationId": "getPricing",
        "summary": "Letter product pricing snapshot",
        "description": "Returns the live complaint-letter checkout configuration. Agents should still send users to /pricing or /letter for final human-visible pricing before purchase.",
        "responses": {
          "200": {
            "description": "Pricing",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PricingResponse" },
                "examples": {
                  "paid": {
                    "value": {
                      "paymentsRequired": true,
                      "letterPricePence": 299,
                      "pricePlanId": "standard",
                      "currency": "GBP"
                    }
                  },
                  "waived": {
                    "value": {
                      "paymentsRequired": false,
                      "letterPricePence": 0,
                      "pricePlanId": "waived",
                      "currency": "GBP"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/lenders": {
      "get": {
        "tags": ["Reference"],
        "operationId": "listLenders",
        "summary": "Public lender id and name list",
        "description": "Returns lender IDs and display names used by the complaint letter flow. This endpoint does not return customer-specific data.",
        "responses": {
          "200": {
            "description": "Lender list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/LenderListResponse" },
                "examples": {
                  "example": {
                    "value": {
                      "lenders": [
                        { "id": "black-horse", "name": "Black Horse" },
                        { "id": "santander-consumer-finance", "name": "Santander Consumer Finance" }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/calculate-dca-refund": {
      "post": {
        "tags": ["Calculator"],
        "operationId": "calculateDcaRefund",
        "summary": "Calculate an illustrative DCA-style refund estimate",
        "description": "Use this endpoint when a user asks for an illustrative estimate of possible DCA / discretionary commission refund value. Results are educational only and are not a promise of lender, FOS, or FCA redress.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/DcaCalculationRequest" },
              "examples": {
                "typicalAgreement": {
                  "summary": "Typical PCP or HP agreement",
                  "value": {
                    "amountFinanced": 15000,
                    "aprPaid": 9.9,
                    "loanTermYears": 4,
                    "agreementStartDate": "2018-06-01",
                    "fairRate": 4
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DcaCalculationResponse" },
                "examples": {
                  "result": {
                    "value": {
                      "result": {
                        "estimatedRefund": 2868,
                        "overpaidInterest": 1970,
                        "statutoryInterest": 898
                      },
                      "disclaimer": "Illustrative estimate only - not a promise of redress; final outcomes follow lender, FOS, or FCA scheme rules."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation errors",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" },
                "examples": {
                  "missingField": {
                    "value": {
                      "errors": {
                        "amountFinanced": "Amount financed is required"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AgentInfo": {
        "type": "object",
        "required": ["service", "name", "canonicalUrl", "tools", "disclaimer"],
        "properties": {
          "service": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "canonicalUrl": { "type": "string", "format": "uri" },
          "llmsTxt": { "type": "string", "format": "uri" },
          "openapi": { "type": "string", "format": "uri" },
          "tools": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/AgentTool" }
          },
          "trustSignals": {
            "type": "array",
            "items": { "type": "string" }
          },
          "disclaimer": { "type": "string" }
        }
      },
      "AgentTool": {
        "type": "object",
        "required": ["id", "name", "uiUrl", "markdownUrl"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "uiUrl": { "type": "string", "format": "uri" },
          "markdownUrl": { "type": "string", "format": "uri" },
          "api": {
            "type": "object",
            "properties": {
              "method": { "type": "string", "enum": ["GET", "POST"] },
              "url": { "type": "string", "format": "uri" }
            }
          },
          "useWhen": { "type": "string" }
        }
      },
      "HealthResponse": {
        "type": "object",
        "required": ["status", "service", "time"],
        "properties": {
          "status": { "type": "string", "example": "ok" },
          "service": { "type": "string" },
          "time": { "type": "string", "format": "date-time" }
        }
      },
      "PricingResponse": {
        "type": "object",
        "required": ["paymentsRequired", "letterPricePence", "pricePlanId", "currency"],
        "properties": {
          "paymentsRequired": { "type": "boolean" },
          "letterPricePence": { "type": "integer", "minimum": 0 },
          "pricePlanId": { "type": "string" },
          "currency": { "type": "string", "example": "GBP" }
        }
      },
      "LenderListResponse": {
        "type": "object",
        "required": ["lenders"],
        "properties": {
          "lenders": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Lender" }
          }
        }
      },
      "Lender": {
        "type": "object",
        "required": ["id", "name"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" }
        }
      },
      "DcaCalculationRequest": {
        "type": "object",
        "required": ["amountFinanced", "aprPaid", "loanTermYears", "agreementStartDate"],
        "properties": {
          "amountFinanced": {
            "type": "number",
            "minimum": 1,
            "description": "Amount borrowed, excluding deposit, in GBP."
          },
          "aprPaid": {
            "type": "number",
            "minimum": 0,
            "description": "APR percentage shown on the finance agreement."
          },
          "loanTermYears": {
            "type": "number",
            "minimum": 1,
            "maximum": 7
          },
          "agreementStartDate": {
            "type": "string",
            "format": "date",
            "description": "ISO date for the agreement start, e.g. 2018-06-01."
          },
          "fairRate": {
            "type": "number",
            "default": 4,
            "description": "Benchmark APR percentage used for comparison."
          }
        }
      },
      "DcaCalculationResponse": {
        "type": "object",
        "required": ["result", "disclaimer"],
        "properties": {
          "result": {
            "type": "object",
            "description": "Calculation result object. Exact keys may evolve as the calculator model is refined."
          },
          "disclaimer": { "type": "string" }
        }
      },
      "ValidationErrorResponse": {
        "type": "object",
        "required": ["errors"],
        "properties": {
          "errors": {
            "type": "object",
            "additionalProperties": { "type": "string" }
          }
        }
      }
    }
  },
  "x-agent-guidance": {
    "preferredDiscoveryOrder": [
      "https://carfinancerefundletter.co.uk/llms.txt",
      "https://carfinancerefundletter.co.uk/api/agent-info",
      "https://carfinancerefundletter.co.uk/openapi.json"
    ],
    "calculator": "Call POST /calculate-dca-refund for illustrative estimates, then cite /calculator or /calculator.md.",
    "letterGenerator": "Send users to /letter to generate the PDF complaint letter; cite /letter.md for agent-readable summary.",
    "disclaimer": "Do not present outputs as official FCA, lender, FOS, legal, or financial advice."
  }
}