{
  "openapi": "3.1.1",
  "info": {
    "title": "Skyfold Aurora Outlook API",
    "version": "1.0.0",
    "summary": "Chance of seeing the northern or southern lights at your place for the next three nights.",
    "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp."
  },
  "servers": [
    {
      "url": "https://skyfoldauroraoutlook.usefulweb.site"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Chance of seeing the northern or southern lights at your place for the next three nights.",
        "description": "Combines the NOAA SWPC Kp forecast with your geomagnetic latitude (IGRF-14 dipole), the darkness of each 3-hour period and the MET Norway cloud forecast into chance bands per period and night, and tells you which Kp you need for aurora overhead, on the horizon or on camera.\n\nMethodology:\n- Geomagnetic latitude: centred dipole from the IGRF-14 degree-1 coefficients (epoch 2025.0 plus secular variation); the north pole is computed at 80.85° N, 72.76° W for 2025.0 as published.\n- Oval boundary near magnetic midnight: 67.29° − 1.893° × Kp (mean of the 23–01 MLT fits of Carbary 2005).\n- Chance bands from your latitude minus the boundary: at or poleward of it high (aurora overhead possible), up to 4° equatorward moderate (low on the poleward horizon), up to 8° low (faint, camera only), further very low.\n- Each 3-hour period counts as dark when the Sun is 12° or more below the horizon for at least half of it; 50 % cloud lowers the band by one step, 80 % by two.\n\nAurora forecasts are probabilistic: Kp forecasts for more than a day ahead are often off by 1–2, substorms come and go within minutes, and the dipole latitude can differ from the corrected geomagnetic latitude by a few degrees. Treat the bands as chances, not promises.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "skyfold_aurora_outlook",
        "x-owner-app": "skyfold",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SkyfoldAuroraOutlookInput"
              },
              "examples": {
                "example1": {
                  "summary": "Oslo with the forecast of 8 November 2026",
                  "value": {
                    "location": "59.9139, 10.7522",
                    "timeZone": "Europe/Oslo",
                    "source": "paste",
                    "kpText": ":Product: 3-Day Forecast\n:Issued: 2026 Nov 08 1230 UTC\n# Prepared by the U.S. Dept. of Commerce, NOAA, Space Weather Prediction Center\nNOAA Kp index breakdown Nov 08-Nov 10 2026\n             Nov 08       Nov 09       Nov 10\n00-03UT       5.00 (G1)    3.67         3.67\n03-06UT       3.33         4.67 (G1)    3.67\n06-09UT       3.00         3.67         2.67\n09-12UT       3.33         3.00         2.67\n12-15UT       2.67         2.67         1.67\n15-18UT       2.67         2.67         1.67\n18-21UT       3.67         2.67         1.67\n21-00UT       4.67 (G1)    3.67         2.67",
                    "clouds": false
                  }
                },
                "example2": {
                  "summary": "Edinburgh with the same forecast",
                  "value": {
                    "location": "55.9533, -3.1883",
                    "elevation": 50,
                    "timeZone": "Europe/London",
                    "source": "paste",
                    "kpText": ":Product: 3-Day Forecast\n:Issued: 2026 Nov 08 1230 UTC\n# Prepared by the U.S. Dept. of Commerce, NOAA, Space Weather Prediction Center\nNOAA Kp index breakdown Nov 08-Nov 10 2026\n             Nov 08       Nov 09       Nov 10\n00-03UT       5.00 (G1)    3.67         3.67\n03-06UT       3.33         4.67 (G1)    3.67\n06-09UT       3.00         3.67         2.67\n09-12UT       3.33         3.00         2.67\n12-15UT       2.67         2.67         1.67\n15-18UT       2.67         2.67         1.67\n18-21UT       3.67         2.67         1.67\n21-00UT       4.67 (G1)    3.67         2.67",
                    "clouds": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SkyfoldAuroraOutlookResult"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON body.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid input (see errors[]).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (see Retry-After).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tool": {
      "get": {
        "operationId": "getToolDefinition",
        "summary": "Inputs, output schema and examples for this tool",
        "responses": {
          "200": {
            "description": "Tool definition.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details. 422 responses include per-field `errors`.",
        "required": [
          "type",
          "title",
          "status",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "field",
                "message"
              ],
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "SkyfoldAuroraOutlookInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "location": {
            "title": "Location (latitude, longitude)",
            "description": "Decimal degrees such as 52.09, 5.12 (north and east positive), or DMS, UTM, MGRS, Maidenhead or a plus code.",
            "type": "string",
            "maxLength": 80,
            "default": "59.9139, 10.7522"
          },
          "elevation": {
            "title": "Elevation above sea level",
            "type": "number",
            "minimum": -500,
            "maximum": 9000,
            "default": 0,
            "x-unit": "m"
          },
          "timeZone": {
            "title": "Time zone",
            "description": "IANA name such as Europe/Berlin or America/New_York, or a fixed offset such as UTC+2.",
            "type": "string",
            "maxLength": 64,
            "default": "Europe/Oslo"
          },
          "source": {
            "title": "Kp forecast",
            "type": "string",
            "enum": [
              "noaa",
              "paste"
            ],
            "default": "noaa"
          },
          "kpText": {
            "title": "Kp forecast text or JSON (when pasted)",
            "description": "The NOAA “3-Day Forecast” text or the planetary K-index forecast JSON.",
            "type": "string",
            "maxLength": 60000,
            "default": ""
          },
          "clouds": {
            "title": "Add the cloud forecast from MET Norway",
            "description": "Only with the fetched forecast; the place is rounded to 0.01° for the request.",
            "type": "boolean",
            "default": true
          }
        },
        "required": []
      },
      "SkyfoldAuroraOutlookResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schemaVersion",
          "tool",
          "computedAt",
          "inputs",
          "summary",
          "result",
          "units",
          "assumptions",
          "sources",
          "warnings",
          "presentation",
          "links"
        ],
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1.0"
          },
          "tool": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "version"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "version": {
                "type": "string"
              }
            }
          },
          "computedAt": {
            "type": "string",
            "format": "date-time"
          },
          "inputs": {
            "type": "object",
            "description": "Normalised inputs actually used, including applied defaults."
          },
          "summary": {
            "type": "string"
          },
          "result": {
            "type": "object"
          },
          "units": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "assumptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "publisher": {
                  "type": "string"
                },
                "retrievedAt": {
                  "type": "string"
                },
                "note": {
                  "type": "string"
                }
              }
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "presentation": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Display blocks used by the human page (same data)."
          },
          "links": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "human",
              "api",
              "openapi",
              "methodology"
            ],
            "properties": {
              "human": {
                "type": "string",
                "format": "uri"
              },
              "api": {
                "type": "string",
                "format": "uri"
              },
              "openapi": {
                "type": "string",
                "format": "uri"
              },
              "methodology": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}