{
  "openapi": "3.1.0",
  "info": {
    "title": "RateRecon",
    "version": "0.1",
    "summary": "UK savings best-buy register for AI agents",
    "description": "Best UK retail savings rates by category with the decision rules an AI agent needs to pick the best net yield for a person. Factual information, not advice. No authentication. Rate limit: be reasonable; the feed changes at most a few times a day.",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://raterecon.co.uk",
      "description": "Production"
    },
    {
      "url": "./",
      "description": "This deployment, relative"
    }
  ],
  "paths": {
    "/rates.json": {
      "get": {
        "operationId": "getRates",
        "summary": "Whole register with decision rules",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "as_of",
                    "products",
                    "decision_rules"
                  ],
                  "properties": {
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "schema_version": {
                      "type": "string"
                    },
                    "licence": {
                      "type": "string"
                    },
                    "counts": {
                      "type": "object"
                    },
                    "field_glossary": {
                      "type": "object"
                    },
                    "macro": {
                      "type": "object"
                    },
                    "decision_rules": {
                      "type": "object"
                    },
                    "products": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "provider",
                          "product",
                          "category",
                          "wrapper",
                          "aer",
                          "rate_type",
                          "effective_12m_aer",
                          "min_deposit",
                          "fscs",
                          "sources",
                          "checked",
                          "confidence"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "provider": {
                            "type": "string"
                          },
                          "product": {
                            "type": "string"
                          },
                          "category": {
                            "type": "string",
                            "enum": [
                              "easy_access",
                              "notice",
                              "fixed",
                              "regular_saver"
                            ]
                          },
                          "wrapper": {
                            "type": "string",
                            "enum": [
                              "none",
                              "cash_isa"
                            ]
                          },
                          "aer": {
                            "type": "number",
                            "description": "Annual Equivalent Rate, percent"
                          },
                          "effective_12m_aer": {
                            "type": "number",
                            "description": "AER blended over 12 months when a bonus ends earlier"
                          },
                          "rate_type": {
                            "type": "string",
                            "enum": [
                              "variable",
                              "fixed",
                              "expected_profit"
                            ]
                          },
                          "bonus": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "points": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "months": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "reverts_to_aer": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              }
                            }
                          },
                          "term_months": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "notice_days": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "min_deposit": {
                            "type": "number"
                          },
                          "max_deposit": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "monthly_max": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "withdrawals": {
                            "type": "string"
                          },
                          "interest_paid": {
                            "type": "string"
                          },
                          "open_via": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "flags": {
                            "type": "object",
                            "properties": {
                              "new_customers_only": {
                                "type": "boolean"
                              },
                              "existing_customers_only": {
                                "type": "boolean"
                              },
                              "app_only": {
                                "type": "boolean"
                              },
                              "shariah": {
                                "type": "boolean"
                              },
                              "requires_other_product": {
                                "type": "boolean"
                              }
                            }
                          },
                          "agent_flags": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "fscs": {
                            "type": "object",
                            "properties": {
                              "covered": {
                                "type": "boolean"
                              },
                              "licence": {
                                "type": "string"
                              },
                              "shared_licence": {
                                "type": "boolean"
                              },
                              "note": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          },
                          "sources": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "url": {
                                  "type": "string",
                                  "format": "uri"
                                },
                                "checked": {
                                  "type": "string",
                                  "format": "date"
                                }
                              }
                            }
                          },
                          "checked": {
                            "type": "string",
                            "format": "date"
                          },
                          "confidence": {
                            "type": "string",
                            "enum": [
                              "high",
                              "medium"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "summary": "llms.txt index",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {}
            }
          }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "operationId": "getLlmsFull",
        "summary": "Full register as plain text",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {}
            }
          }
        }
      }
    },
    "/recommend.js": {
      "get": {
        "operationId": "getRecommendJs",
        "summary": "Reference ranking logic",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/javascript": {}
            }
          }
        }
      }
    },
    "/v1/recommend": {
      "post": {
        "operationId": "recommend",
        "summary": "Best net-yield plan for a person (planned)",
        "x-status": "planned",
        "description": "Until this ships, fetch /rates.json and run /recommend.js locally; the response shape is identical.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "amount"
                ],
                "properties": {
                  "amount": {
                    "type": "number",
                    "minimum": 0
                  },
                  "access": {
                    "type": "string",
                    "enum": [
                      "instant",
                      "notice_90",
                      "fix_12",
                      "fix_24",
                      "fix_60"
                    ],
                    "default": "instant"
                  },
                  "tax_band": {
                    "type": "string",
                    "enum": [
                      "none",
                      "basic",
                      "higher",
                      "additional"
                    ],
                    "default": "basic"
                  },
                  "isa_allowance_remaining": {
                    "type": "number",
                    "default": 20000
                  },
                  "psa_remaining": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "include_bonus": {
                    "type": "boolean",
                    "default": true
                  },
                  "include_shariah": {
                    "type": "boolean",
                    "default": true
                  },
                  "include_app_only": {
                    "type": "boolean",
                    "default": true
                  },
                  "include_new_customer_only": {
                    "type": "boolean",
                    "default": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Plan",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "as_of": {
                      "type": "string"
                    },
                    "query": {
                      "type": "object"
                    },
                    "plan": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "product_id": {
                            "type": "string"
                          },
                          "provider": {
                            "type": "string"
                          },
                          "product": {
                            "type": "string"
                          },
                          "wrapper": {
                            "type": "string"
                          },
                          "amount_gbp": {
                            "type": "number"
                          },
                          "aer": {
                            "type": "number"
                          },
                          "effective_12m_aer": {
                            "type": "number"
                          },
                          "est_gross_interest_12m_gbp": {
                            "type": "number"
                          },
                          "est_net_interest_12m_gbp": {
                            "type": "number"
                          },
                          "flags": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "fscs": {
                            "type": "object"
                          }
                        }
                      }
                    },
                    "placed_gbp": {
                      "type": "number"
                    },
                    "total_est_net_interest_12m_gbp": {
                      "type": "number"
                    },
                    "blended_net_rate_pct": {
                      "type": "number"
                    },
                    "assumptions": {
                      "type": "object"
                    },
                    "alternatives": {
                      "type": "object"
                    },
                    "drip_feed": {
                      "type": "array"
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}