{
  "openapi": "3.1.0",
  "info": {
    "title": "Birthday Color API",
    "version": "1.0.0",
    "description": "A public read-only API for looking up the birthday color of any calendar date, including English, Japanese, and Chinese color data. Public claims, user messages, IP addresses, and analytics data are intentionally excluded.",
    "license": {
      "name": "Attribution requested",
      "url": "https://birthdaycolor.top/"
    }
  },
  "servers": [
    {
      "url": "https://birthdaycolor.top",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Human-readable API documentation",
    "url": "https://birthdaycolor.top/en/developers"
  },
  "tags": [
    {
      "name": "Birthday Colors",
      "description": "Read-only birthday color data by calendar date."
    }
  ],
  "paths": {
    "/api/v1/days/{date}": {
      "get": {
        "tags": ["Birthday Colors"],
        "operationId": "getBirthdayColorByDate",
        "summary": "Get the birthday color for a calendar date",
        "description": "Returns the color hex value, localized names, keywords, descriptions, and date-page URLs for one MM-DD calendar date. February 29 is supported.",
        "parameters": [
          {
            "name": "date",
            "in": "path",
            "required": true,
            "description": "Calendar date in MM-DD format. February 29 is supported.",
            "schema": {
              "type": "string",
              "pattern": "^(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$",
              "examples": ["06-02", "02-29"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Birthday color data for the requested date.",
            "headers": {
              "Cache-Control": {
                "description": "Responses may be cached by shared caches.",
                "schema": { "type": "string" }
              },
              "Access-Control-Allow-Origin": {
                "description": "The endpoint is publicly readable from browsers.",
                "schema": { "type": "string", "example": "*" }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BirthdayColorResponse"
                },
                "examples": {
                  "juneSecond": {
                    "summary": "June 2 birthday color",
                    "value": {
                      "api_version": "v1",
                      "date": "06-02",
                      "color": {
                        "hex": "#7058A3",
                        "name": {
                          "en": "Violet",
                          "ja": "菫色",
                          "zh": "堇紫"
                        },
                        "keywords": {
                          "en": ["whimsy", "generosity", "charm"],
                          "ja": ["気まぐれ", "気前", "チャーミング"],
                          "zh": ["随性", "大方", "迷人"]
                        },
                        "description": {
                          "en": "The birthday color for June 2 is Violet. Its keywords are whimsy, generosity, charm.",
                          "ja": "6月2日の誕生色は菫色（すみれいろ）です。色言葉：気まぐれ、気前、チャーミング。",
                          "zh": "6月2日的生日色是堇紫。关键词是：随性、大方、迷人。"
                        }
                      },
                      "urls": {
                        "en": "https://birthdaycolor.top/en/day/06-02",
                        "ja": "https://birthdaycolor.top/ja/day/06-02",
                        "zh": "https://birthdaycolor.top/zh/day/06-02"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "The date is not a supported calendar date.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Only GET and OPTIONS are supported.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BirthdayColorResponse": {
        "type": "object",
        "required": ["api_version", "date", "color", "urls"],
        "properties": {
          "api_version": {
            "type": "string",
            "const": "v1"
          },
          "date": {
            "type": "string",
            "pattern": "^(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$",
            "example": "06-02"
          },
          "color": {
            "type": "object",
            "required": ["hex", "name", "keywords", "description"],
            "properties": {
              "hex": {
                "type": "string",
                "pattern": "^#[0-9A-Fa-f]{6}$",
                "example": "#7058A3"
              },
              "name": {
                "$ref": "#/components/schemas/LocalizedText"
              },
              "keywords": {
                "$ref": "#/components/schemas/LocalizedKeywords"
              },
              "description": {
                "$ref": "#/components/schemas/LocalizedText"
              }
            }
          },
          "urls": {
            "$ref": "#/components/schemas/LocalizedText"
          }
        }
      },
      "LocalizedText": {
        "type": "object",
        "required": ["en", "ja", "zh"],
        "properties": {
          "en": { "type": "string" },
          "ja": { "type": "string" },
          "zh": { "type": "string" }
        },
        "additionalProperties": false
      },
      "LocalizedKeywords": {
        "type": "object",
        "required": ["en", "ja", "zh"],
        "properties": {
          "en": { "type": "array", "items": { "type": "string" } },
          "ja": { "type": "array", "items": { "type": "string" } },
          "zh": { "type": "array", "items": { "type": "string" } }
        },
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string",
            "examples": ["day_not_found", "method_not_allowed"]
          }
        },
        "additionalProperties": true
      }
    }
  }
}