{
  "openapi": "3.1.0",
  "info": {
    "title": "Surfski Index API",
    "version": "1.0.0",
    "description": "Read-only search over the Surfski Index catalogue. Stability and speed are Surfski Index estimates, not maker figures or timed tests. Every response carries the caveat, terms and a cite_as line per craft; link to each craft url when you use it. Prices are not included. Fair use: about 60 requests a minute per address. MCP clients can use the same data at https://surfskiindex.com/mcp."
  },
  "servers": [
    {
      "url": "https://surfskiindex.com"
    }
  ],
  "paths": {
    "/api/v1/search": {
      "get": {
        "operationId": "searchSurfskis",
        "summary": "Search craft by words and filters",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Words to match against name, maker and description"
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "surfski",
                "double",
                "triple",
                "flatwater-trainer",
                "oc1-outrigger",
                "surf-lifesaving-spec",
                "ski-touring"
              ]
            },
            "description": "Craft type"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "current",
                "historical",
                "all"
              ],
              "default": "current"
            },
            "description": "In production, out of production, or both"
          },
          {
            "name": "weight",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 30,
              "maximum": 200
            },
            "description": "Paddler weight in kg; adds a fit label"
          },
          {
            "name": "fit_only",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "With weight, only craft whose weight guide suits it"
          },
          {
            "name": "min_stability",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 10
            },
            "description": "Stability band reaches at least this"
          },
          {
            "name": "max_stability",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 10
            },
            "description": "Stability band reaches at most this"
          },
          {
            "name": "min_speed",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 10
            },
            "description": "Speed rating at least this"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "relevance",
                "stability",
                "speed",
                "name"
              ]
            },
            "description": "Result order"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 10
            },
            "description": "Results to return"
          }
        ],
        "responses": {
          "200": {
            "description": "Matching craft",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad parameter"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/v1/craft/{id}": {
      "get": {
        "operationId": "getSurfski",
        "summary": "One craft in full",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Craft id from search, e.g. epic-v10"
          },
          {
            "name": "weight",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 30,
              "maximum": 200
            },
            "description": "Paddler weight in kg; adds a fit label"
          }
        ],
        "responses": {
          "200": {
            "description": "The craft",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad parameter"
          },
          "404": {
            "description": "No such craft"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/v1/fit": {
      "get": {
        "operationId": "findSurfskisForPaddler",
        "summary": "In-production craft whose weight guide suits a paddler",
        "parameters": [
          {
            "name": "weight",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number",
              "minimum": 30,
              "maximum": 200
            },
            "description": "Paddler weight in kg"
          },
          {
            "name": "skill",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "beginner",
                "intermediate",
                "advanced",
                "elite"
              ]
            },
            "description": "Keep craft usually paddled at or below this level"
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "surfski",
                "double",
                "triple",
                "flatwater-trainer",
                "oc1-outrigger",
                "surf-lifesaving-spec",
                "ski-touring"
              ],
              "default": "surfski"
            },
            "description": "Craft type"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "stability",
                "speed"
              ],
              "default": "stability"
            },
            "description": "Order within each fit group"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 10
            },
            "description": "Results to return"
          }
        ],
        "responses": {
          "200": {
            "description": "Shortlist, central weight band first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad parameter"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    }
  }
}