{"openapi":"3.1.0","info":{"title":"Thermocast API","summary":"Data-driven thermospheric mass-density predictions for LEO altitudes (250–600 km).","description":"Thermocast serves machine-learned **thermospheric mass-density** predictions at\naltitudes between 250 km and 600 km — the regime occupied by most low-Earth-orbit\nsatellites. It is designed for space-weather, satellite-drag, and orbit-determination\nworkflows.\n\n### What the model returns\nAll endpoints return **point predictions** of neutral mass density in kg/m³.\nThe current model does **not** emit per-prediction uncertainty; use\n[`/about`](./about) to inspect the model version and valid datetime range, and\nconsult response headers (`X-Model-Version`, `X-Model-Train-Date`,\n`X-Thermocast-Version`) to pin the exact model that produced a response.\n\n### Choosing an endpoint\n* [`/surface`](./surface) — a 100×100 lat/lon grid at one altitude (preferred for maps).\n* [`/surface/all`](./surface/all) — the same grid at every supported altitude.\n* [`/altitude`](./altitude) — a density profile across altitudes at one location.\n* [`/density`](./density) — a single point. Prefer the batch endpoints; this one\n  exists for one-off lookups only.\n* [`/geomag`](./geomag) — the space-weather drivers (Kp, Dst, F10.7) the model\n  consumes, exposed for inspection.\n\n### Grid convention\nReturned `latitude` / `longitude` arrays are flattened in row-major order (lon varies\nfastest) and align element-wise with the flattened density grid.","termsOfService":"https://trillium.tech","contact":{"name":"Trillium Technologies","url":"https://trillium.tech/"},"license":{"name":"Proprietary — contact Trillium Technologies","url":"https://trillium.tech/"},"version":"0.0.1","x-logo":{"url":"https://thermocast.spaceml.org/logo.png","altText":"ThermoCast","href":"https://thermocast.spaceml.org/"}},"servers":[{"url":"https://thermocast.spaceml.org/api","description":"Production"}],"paths":{"/":{"get":{"tags":["metadata"],"summary":"Service discovery document.","description":"Return a JSON discovery document with pointers to documentation, the OpenAPI spec, the LLM agent summaries, model metadata, and the source repository. Agents that hit the API root should start here.","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RootDiscoveryResponse"}}}}}}},"/surface":{"get":{"tags":["forecast"],"summary":"Density map at a single altitude.","description":"Return a 100x100 lat/lon grid of thermospheric mass density (kg/m^3) at the requested altitude and time. Altitudes must be one of 250, 300, 350, 400, 450, 500, 550, or 600 km. Results are server-side cached for 120s. Responses carry `X-Model-Version` and `X-Model-Train-Date` headers.","operationId":"get_surface_surface_get","parameters":[{"name":"altitude","in":"query","required":true,"schema":{"type":"number","title":"Altitude"}},{"name":"date_time","in":"query","required":false,"schema":{"type":"string","format":"date-time","title":"Date Time"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurfaceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/surface/all":{"get":{"tags":["forecast"],"summary":"Density maps at every supported altitude.","description":"Return density grids at all eight supported altitudes (250..600 km in 50 km steps) for the requested time. Use this in preference to calling `/surface` eight times. Cached for 120s server-side.","operationId":"get_surface_all_surface_all_get","parameters":[{"name":"date_time","in":"query","required":false,"schema":{"type":"string","format":"date-time","title":"Date Time"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurfaceAllResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/altitude":{"get":{"tags":["forecast"],"summary":"Vertical density profile at one location.","description":"Return mass density (kg/m^3) at every supported altitude (250..600 km in 50 km steps) for a single latitude/longitude and time. Cached for 120s server-side.","operationId":"get_altitude_altitude_get","parameters":[{"name":"latitude","in":"query","required":true,"schema":{"type":"number","title":"Latitude"}},{"name":"longitude","in":"query","required":true,"schema":{"type":"number","title":"Longitude"}},{"name":"date_time","in":"query","required":false,"schema":{"type":"string","format":"date-time","title":"Date Time"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AltitudeProfileResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/density":{"get":{"tags":["advanced"],"summary":"Single-point density prediction (prefer batch endpoints).","description":"Return mass density (kg/m^3) at a single lat/lon/altitude/time. The underlying model evaluates surfaces and volumes in parallel, so batch endpoints (`/surface`, `/surface/all`, `/altitude`) are generally more efficient. Use this endpoint only for one-off point queries. Cached for 120s server-side.","operationId":"get_density_density_get","parameters":[{"name":"latitude","in":"query","required":true,"schema":{"type":"number","title":"Latitude"}},{"name":"longitude","in":"query","required":true,"schema":{"type":"number","title":"Longitude"}},{"name":"altitude","in":"query","required":true,"schema":{"type":"number","title":"Altitude"}},{"name":"date_time","in":"query","required":false,"schema":{"type":"string","format":"date-time","title":"Date Time"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DensityPointResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/about":{"get":{"tags":["metadata"],"summary":"Loaded-model metadata and valid datetime range.","description":"Return the display name, file, version, training date, supported altitude range, and valid datetime range for the currently loaded model. Use this to decide whether a prospective query falls inside the model's coverage before calling a forecast endpoint.","operationId":"get_about_about_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AboutResponse"}}}}}}},"/geomag":{"get":{"tags":["drivers"],"summary":"Geomagnetic and solar indices (Kp, Dst, F10.7).","description":"Return hourly geomagnetic and solar-radio indices used as model drivers. If `date_time` is omitted, the latest available record is returned; otherwise the nearest hour is used. Cached for 300s server-side.","operationId":"get_geomag_geomag_get","parameters":[{"name":"date_time","in":"query","required":false,"schema":{"type":"string","format":"date-time","title":"Date Time"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeomagResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AboutResponse":{"properties":{"model":{"$ref":"#/components/schemas/ModelInfo"},"datetime_range":{"$ref":"#/components/schemas/DatetimeRange"}},"type":"object","required":["model","datetime_range"],"title":"AboutResponse"},"AltitudeProfileResponse":{"properties":{"density":{"items":{"type":"number"},"type":"array","title":"Density","description":"Mass density (kg/m^3) at each altitude."},"altitude":{"items":{"type":"integer"},"type":"array","title":"Altitude","description":"Altitudes (km) corresponding element-wise to `density`."}},"type":"object","required":["density","altitude"],"title":"AltitudeProfileResponse","description":"Density profile across altitudes at a single lat/lon."},"DatetimeRange":{"properties":{"first":{"type":"string","title":"First","description":"ISO datetime of the earliest supported prediction."},"last":{"type":"string","title":"Last","description":"ISO datetime of the latest supported prediction."}},"type":"object","required":["first","last"],"title":"DatetimeRange"},"DensityPointResponse":{"properties":{"density":{"type":"number","title":"Density","description":"Mass density in kg/m^3."},"altitude":{"type":"number","title":"Altitude","description":"Altitude in km."},"latitude":{"type":"number","title":"Latitude","description":"Latitude in degrees."},"longitude":{"type":"number","title":"Longitude","description":"Longitude in degrees."},"date_time":{"type":"string","title":"Date Time","description":"Timestamp of the prediction (UTC, 'YYYY-MM-DD HH:MM:SS')."}},"type":"object","required":["density","altitude","latitude","longitude","date_time"],"title":"DensityPointResponse","description":"A single-point density prediction."},"GeomagResponse":{"properties":{"datetime":{"type":"string","title":"Datetime","description":"ISO datetime of the returned record (hourly)."},"kp":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Kp","description":"Planetary K-index (0..9)."},"dst":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Dst","description":"Disturbance storm-time index (nT)."},"f107":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"F107","description":"F10.7 solar-radio flux (sfu)."}},"type":"object","required":["datetime"],"title":"GeomagResponse","description":"Geomagnetic/solar indices at (or nearest to) a requested hour."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ModelInfo":{"properties":{"display_name":{"type":"string","title":"Display Name"},"model_file":{"type":"string","title":"Model File"},"train_date":{"type":"string","title":"Train Date"},"version":{"type":"string","title":"Version"},"altitude_range_km":{"items":{"type":"integer"},"type":"array","title":"Altitude Range Km"}},"type":"object","required":["display_name","model_file","train_date","version","altitude_range_km"],"title":"ModelInfo"},"RootDiscoveryResponse":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"documentation":{"type":"string","title":"Documentation","description":"Human-readable Swagger UI."},"documentation_redoc":{"type":"string","title":"Documentation Redoc","description":"Alternative ReDoc UI."},"openapi":{"type":"string","title":"Openapi","description":"Machine-readable OpenAPI 3 spec."},"llms_txt":{"type":"string","title":"Llms Txt","description":"Concise summary for LLM agents."},"llms_full_txt":{"type":"string","title":"Llms Full Txt","description":"Long-form agent docs (concepts, conventions, examples)."},"about":{"type":"string","title":"About","description":"Loaded-model metadata and valid datetime range."},"repository":{"type":"string","title":"Repository","description":"Source code repository."},"endpoints":{"items":{"type":"string"},"type":"array","title":"Endpoints","description":"Available API endpoint paths."}},"type":"object","required":["name","description","documentation","documentation_redoc","openapi","llms_txt","llms_full_txt","about","repository","endpoints"],"title":"RootDiscoveryResponse","description":"Top-level discovery document for agents and tooling."},"SurfaceAllResponse":{"properties":{"densities":{"additionalProperties":{"items":{"items":{"type":"number"},"type":"array"},"type":"array"},"type":"object","title":"Densities","description":"Density grids keyed by altitude-in-km as a string ('250', '300', ..., '600'). Each value is a 100x100 grid of kg/m^3."},"altitudes":{"items":{"type":"integer"},"type":"array","title":"Altitudes","description":"Altitudes (km) included in the response."},"latitude":{"items":{"type":"number"},"type":"array","title":"Latitude"},"longitude":{"items":{"type":"number"},"type":"array","title":"Longitude"}},"type":"object","required":["densities","altitudes","latitude","longitude"],"title":"SurfaceAllResponse","description":"All eight altitude levels (250..600 km in 50 km steps) in one response."},"SurfaceResponse":{"properties":{"density":{"items":{"items":{"type":"number"},"type":"array"},"type":"array","title":"Density","description":"Mass density (kg/m^3) as a 100x100 grid. Rows index longitude, columns index latitude."},"latitude":{"items":{"type":"number"},"type":"array","title":"Latitude","description":"Flattened latitude (degrees, -90..90) aligned element-wise with the flattened density grid."},"longitude":{"items":{"type":"number"},"type":"array","title":"Longitude","description":"Flattened longitude (degrees, -180..180) aligned element-wise with the flattened density grid."}},"type":"object","required":["density","latitude","longitude"],"title":"SurfaceResponse","description":"Flattened 100x100 grid of mass densities at a single altitude."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"forecast","description":"Endpoints that return model density predictions. Responses carry `X-Model-Version` and `X-Model-Train-Date` response headers so agents can pin the exact model that produced a response."},{"name":"drivers","description":"Geomagnetic and solar indices consumed by the model."},{"name":"metadata","description":"Information about the API itself and the loaded model."},{"name":"advanced","description":"Endpoints intended for specialist use. The primary forecast endpoints cover the common cases more efficiently."}],"externalDocs":{"description":"Long-form documentation for LLM agents (concepts, conventions, glossary, worked examples).","url":"https://thermocast.spaceml.org/llms-full.txt"}}