{
  "openapi": "3.0.3",
  "info": {
    "title": "Stardew Valley Wiki API",
    "description": "Free, no-auth JSON API with Stardew Valley game data: fish, crops, villagers, and gift preferences. Maintained alongside a fan-made wiki and planner tools. CORS enabled, no rate limits for reasonable use.",
    "version": "1.0.0",
    "contact": {
      "url": "https://www.stardewvalleywiki.net/developers"
    },
    "license": {
      "name": "CC BY-NC 4.0",
      "url": "https://creativecommons.org/licenses/by-nc/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://www.stardewvalleywiki.net",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/v1/index.json": {
      "get": {
        "summary": "API index",
        "description": "Lists all available datasets with URLs, counts, and summaries.",
        "operationId": "getIndex",
        "tags": ["Meta"],
        "responses": {
          "200": {
            "description": "API metadata and dataset list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Index" }
              }
            }
          }
        }
      }
    },
    "/api/v1/fish.json": {
      "get": {
        "summary": "Fish data",
        "description": "All catchable fish with season, weather, time windows, locations, difficulty, sell prices, bundles, and fish pond data.",
        "operationId": "getFish",
        "tags": ["Game Data"],
        "responses": {
          "200": {
            "description": "Fish dataset envelope",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/Envelope" },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": { "$ref": "#/components/schemas/Fish" }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/crops.json": {
      "get": {
        "summary": "Crop data",
        "description": "Crop data with seasons, growth days, seed costs, sell prices, regrowth, and processing inputs.",
        "operationId": "getCrops",
        "tags": ["Game Data"],
        "responses": {
          "200": {
            "description": "Crops dataset envelope",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/Envelope" },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": { "$ref": "#/components/schemas/Crop" }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/villagers.json": {
      "get": {
        "summary": "Villager data",
        "description": "Villager profiles with birthdays, marriage candidates, addresses, family, and friendship notes.",
        "operationId": "getVillagers",
        "tags": ["Game Data"],
        "responses": {
          "200": {
            "description": "Villagers dataset envelope",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/Envelope" },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": { "$ref": "#/components/schemas/Villager" }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/gifts.json": {
      "get": {
        "summary": "Gift preferences",
        "description": "Per-villager gift taste lists: loves, likes, neutral, dislikes, hates.",
        "operationId": "getGifts",
        "tags": ["Game Data"],
        "responses": {
          "200": {
            "description": "Gifts dataset envelope",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/Envelope" },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": { "$ref": "#/components/schemas/GiftTastes" }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Index": {
        "type": "object",
        "properties": {
          "api_version": { "type": "string", "example": "1.0.0" },
          "game_version": { "type": "string", "example": "1.6" },
          "updated": { "type": "string", "format": "date", "example": "2026-09-17" },
          "source": { "type": "string" },
          "docs": { "type": "string" },
          "datasets": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "dataset": { "type": "string" },
                "url": { "type": "string" },
                "count": { "type": "integer" },
                "summary": { "type": "string" }
              }
            }
          }
        }
      },
      "Envelope": {
        "type": "object",
        "properties": {
          "dataset": { "type": "string", "example": "fish" },
          "api_version": { "type": "string", "example": "1.0.0" },
          "game_version": { "type": "string", "example": "1.6" },
          "updated": { "type": "string", "format": "date" },
          "count": { "type": "integer" },
          "source": { "type": "string" },
          "docs": { "type": "string" },
          "license": { "type": "string" }
        }
      },
      "Fish": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "sardine" },
          "name": { "type": "string", "description": "Chinese name" },
          "name_en": { "type": "string", "example": "Sardine" },
          "location": { "type": "string", "example": "ocean" },
          "season": { "type": "array", "items": { "type": "string", "enum": ["spring", "summer", "fall", "winter"] } },
          "weather": { "type": "string", "example": "any" },
          "time": { "type": "string", "example": "6am - 7pm" },
          "difficulty": { "type": "integer", "minimum": 0, "maximum": 110 },
          "behavior": { "type": "string", "example": "dart" },
          "sell_prices": { "type": "array", "items": { "type": "integer" }, "description": "Base, silver, gold, iridium quality" },
          "is_legendary": { "type": "boolean" },
          "is_crab_pot": { "type": "boolean" },
          "used_in_bundles": { "type": "array", "items": { "type": "string" } },
          "use_in": { "type": "array", "items": { "type": "string" } },
          "fish_pond": { "type": "object" },
          "description": { "type": "string" }
        }
      },
      "Crop": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "parsnip" },
          "name": { "type": "string" },
          "name_en": { "type": "string", "example": "Parsnip" },
          "season": { "type": "array", "items": { "type": "string" } },
          "growth_days": { "type": "integer" },
          "regrowth_days": { "type": "integer", "nullable": true },
          "seed_price": { "type": "integer" },
          "seed_source": { "type": "string" },
          "sell_prices": { "type": "array", "items": { "type": "integer" } },
          "is_trellis": { "type": "boolean" },
          "is_giant": { "type": "boolean" },
          "yield_per_harvest": { "type": "integer" },
          "xp_yield": { "type": "integer" },
          "bundle": { "type": "string" },
          "heals": { "type": "object", "properties": { "hp": { "type": "integer" }, "energy": { "type": "integer" } } },
          "use_in": { "type": "array", "items": { "type": "string" } },
          "description": { "type": "string" }
        }
      },
      "Villager": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "abigail" },
          "name": { "type": "string" },
          "name_en": { "type": "string", "example": "Abigail" },
          "gender": { "type": "string", "enum": ["male", "female"] },
          "birthday": { "type": "string", "example": "fall_13" },
          "marriageable": { "type": "boolean" },
          "lives_in": { "type": "string" },
          "address": { "type": "string" },
          "family": { "type": "array", "items": { "type": "string" } },
          "family_detail": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "relation": { "type": "string" } } } },
          "best_gifts": { "type": "array", "items": { "type": "string" } },
          "description": { "type": "string" }
        }
      },
      "GiftTastes": {
        "type": "object",
        "properties": {
          "npc": { "type": "string", "example": "abigail" },
          "loves": { "type": "array", "items": { "type": "string" } },
          "likes": { "type": "array", "items": { "type": "string" } },
          "neutral": { "type": "array", "items": { "type": "string" } },
          "dislikes": { "type": "array", "items": { "type": "string" } },
          "hates": { "type": "array", "items": { "type": "string" } }
        }
      }
    }
  },
  "tags": [
    { "name": "Meta", "description": "API metadata" },
    { "name": "Game Data", "description": "Stardew Valley game datasets" }
  ]
}
