{
  "info": {
    "description": "Public API for Cyclesite — the UK's used bicycle marketplace. Search bikes, get valuations, check stolen status, and view market data. No authentication required.",
    "title": "Cyclesite Public API",
    "version": "1.1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/api/mcp/search": {
      "get": {
        "description": "Search active bike listings. Returns up to 5 results with attribution. No authentication required. Rate limited: 20 requests per minute.",
        "operationId": "searchBikes",
        "parameters": [
          {
            "description": "Bike brand (case-insensitive)",
            "in": "query",
            "name": "brand",
            "required": false,
            "schema": {
              "description": "Bike brand (case-insensitive)",
              "type": "string"
            }
          },
          {
            "description": "Bike category (road, mtb, gravel, hybrid, ebike, etc.)",
            "in": "query",
            "name": "category",
            "required": false,
            "schema": {
              "description": "Bike category (road, mtb, gravel, hybrid, ebike, etc.)",
              "type": "string"
            }
          },
          {
            "description": "UK city (case-insensitive)",
            "in": "query",
            "name": "city",
            "required": false,
            "schema": {
              "description": "UK city (case-insensitive)",
              "type": "string"
            }
          },
          {
            "description": "Minimum price in GBP",
            "in": "query",
            "name": "minPrice",
            "required": false,
            "schema": {
              "description": "Minimum price in GBP",
              "nullable": true,
              "type": "number"
            }
          },
          {
            "description": "Maximum price in GBP",
            "in": "query",
            "name": "maxPrice",
            "required": false,
            "schema": {
              "description": "Maximum price in GBP",
              "nullable": true,
              "type": "number"
            }
          },
          {
            "description": "Condition (Excellent, Very_Good, Good, Fair, Poor, For_Parts)",
            "in": "query",
            "name": "condition",
            "required": false,
            "schema": {
              "description": "Condition (Excellent, Very_Good, Good, Fair, Poor, For_Parts)",
              "type": "string"
            }
          },
          {
            "description": "Max results (1-5, default 5)",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "description": "Max results (1-5, default 5)",
              "nullable": true,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "attribution": {
                      "type": "string"
                    },
                    "listings": {
                      "items": {
                        "properties": {
                          "brand": {
                            "nullable": true,
                            "type": "string"
                          },
                          "city": {
                            "nullable": true,
                            "type": "string"
                          },
                          "condition": {
                            "nullable": true,
                            "type": "string"
                          },
                          "model": {
                            "nullable": true,
                            "type": "string"
                          },
                          "priceGbp": {
                            "nullable": true,
                            "type": "number"
                          },
                          "title": {
                            "type": "string"
                          },
                          "url": {
                            "nullable": true,
                            "type": "string"
                          },
                          "year": {
                            "nullable": true,
                            "type": "number"
                          }
                        },
                        "required": [
                          "title",
                          "priceGbp",
                          "condition",
                          "city",
                          "brand",
                          "model",
                          "year",
                          "url"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "resultsCount": {
                      "type": "number"
                    }
                  },
                  "required": ["attribution", "resultsCount", "listings"],
                  "type": "object"
                }
              }
            },
            "description": "Search results"
          },
          "429": {
            "description": "Rate limited"
          }
        },
        "security": [],
        "summary": "Search bikes for sale",
        "tags": ["MCP API"]
      }
    },
    "/api/mcp/stolen-check": {
      "post": {
        "description": "Check a frame/serial number against UK police databases, BikeRegister, and community registries. Returns status (clear/caution/stolen) with confidence level. No authentication required. Per-serial rate limited.",
        "operationId": "checkStolen",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "serial": {
                    "description": "Bike frame/serial number",
                    "maxLength": 50,
                    "minLength": 4,
                    "type": "string"
                  }
                },
                "required": ["serial"],
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "action": {
                      "type": "string"
                    },
                    "attribution": {
                      "type": "string"
                    },
                    "checkedAt": {
                      "type": "string"
                    },
                    "confidence": {
                      "maximum": 100,
                      "minimum": 0,
                      "type": "number"
                    },
                    "confidenceLabel": {
                      "enum": ["high", "medium", "low"],
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "sourcesChecked": {
                      "type": "number"
                    },
                    "status": {
                      "enum": ["clear", "caution", "stolen"],
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "status",
                    "confidence",
                    "confidenceLabel",
                    "message",
                    "action",
                    "sourcesChecked",
                    "checkedAt",
                    "url",
                    "attribution"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Stolen check result"
          },
          "429": {
            "description": "Rate limited (per-IP and per-serial)"
          }
        },
        "security": [],
        "summary": "Check if a bike is stolen",
        "tags": ["MCP API"]
      }
    },
    "/api/mcp/valuation": {
      "get": {
        "description": "Valuation summary based on 12-month sold price data. Returns median, min, max prices and active listing count. No authentication required.",
        "operationId": "getValuation",
        "parameters": [
          {
            "description": "Bike brand",
            "in": "query",
            "name": "brand",
            "required": true,
            "schema": {
              "description": "Bike brand",
              "type": "string"
            }
          },
          {
            "description": "Bike model",
            "in": "query",
            "name": "model",
            "required": true,
            "schema": {
              "description": "Bike model",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "activeListingsCount": {
                      "type": "number"
                    },
                    "attribution": {
                      "type": "string"
                    },
                    "maxPriceGbp": {
                      "type": "number"
                    },
                    "medianPriceGbp": {
                      "type": "number"
                    },
                    "minPriceGbp": {
                      "type": "number"
                    },
                    "recentSalesCount": {
                      "type": "number"
                    },
                    "summary": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": ["summary", "attribution"],
                  "type": "object"
                }
              }
            },
            "description": "Valuation summary"
          },
          "429": {
            "description": "Rate limited"
          }
        },
        "security": [],
        "summary": "Get bike valuation",
        "tags": ["MCP API"]
      }
    }
  },
  "servers": [
    {
      "url": "https://www.cyclesite.co.uk"
    }
  ]
}