{
  "openapi": "3.1.1",
  "info": {
    "title": "Skyfold Cosmic Odometer API",
    "version": "1.0.0",
    "summary": "How far you have travelled through space since a date, frame by frame.",
    "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://skyfoldcosmicodometer.usefulweb.app"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "How far you have travelled through space since a date, frame by frame.",
        "description": "From a start date such as your birthday, computes the distance travelled with the Earth’s rotation at your latitude, around the Sun (integrated from VSOP87), around the Milky Way and relative to the cosmic background radiation, with orbits, full Moons and stars whose light left them when you were born.\n\nMethodology:\n- Rotation: circumference of the latitude circle on the WGS84 ellipsoid per sidereal day (86 164.0905 s).\n- Orbit: the Earth’s heliocentric path length, summed from VSOP87 positions every 6 hours (about 940 million km per year).\n- Galaxy: 247 km/s (Reid et al. 2019); cosmic background: 369.82 km/s (Planck 2018). These are separate frames and are not added together.\n- Full Moons: instants of 180° elongation found with the Skyfold Moon theory; light-echo stars: HYG stars brighter than magnitude 6 whose distance in light years is within 3 % of the elapsed years.\n\nGalactic and cosmic speeds carry uncertainties of a few percent; star distances in HYG can be uncertain by 10 % or more for distant stars.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "skyfold_cosmic_odometer",
        "x-owner-app": "skyfold",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SkyfoldCosmicOdometerInput"
              },
              "examples": {
                "example1": {
                  "summary": "Since the year 2000, at the equator",
                  "value": {
                    "startDate": "2000-01-01",
                    "startTime": "00:00",
                    "endDate": "2026-11-07",
                    "timeZone": "UTC",
                    "latitude": 0
                  }
                },
                "example2": {
                  "summary": "Born 17 May 1990 in Utrecht",
                  "value": {
                    "startDate": "1990-05-17",
                    "startTime": "08:00",
                    "endDate": "2026-11-07",
                    "timeZone": "Europe/Amsterdam",
                    "latitude": 52.09
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SkyfoldCosmicOdometerResult"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      },
      "SkyfoldCosmicOdometerInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "startDate": {
            "title": "Start date (for example your birthday)",
            "type": "string",
            "format": "date",
            "default": "2000-01-01"
          },
          "startTime": {
            "title": "Start time",
            "type": "string",
            "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
            "default": "12:00"
          },
          "endDate": {
            "title": "End date",
            "description": "Leave blank for today (UTC date).",
            "type": "string",
            "format": "date"
          },
          "timeZone": {
            "title": "Time zone",
            "type": "string",
            "maxLength": 64,
            "default": "UTC"
          },
          "latitude": {
            "title": "Latitude for Earth’s rotation",
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "default": 0,
            "x-unit": "°"
          }
        },
        "required": []
      },
      "SkyfoldCosmicOdometerResult": {
        "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"
              }
            }
          }
        }
      }
    }
  }
}