{ "openapi": "3.1.0", "info": { "title": "Stellara Astrology API", "version": "1.0.0", "description": "Deterministic Swiss Ephemeris calculations (kerykeion): natal chart, transits with applying/separating aspects, synastry, and birth-place resolution with historically correct time zones. The API computes; it never interprets. Nothing is stored server-side. Authenticate with an API key from https://stellara.natlex.it/#api (Free: 5 requests/day, Stellara API Pro: 5000/day)." }, "servers": [ { "url": "https://api.stellara.natlex.it" } ], "paths": { "/api/v1/astrology/natal": { "post": { "summary": "Natal Chart", "description": "Natal chart: 14 points, 12 house cusps, 4 angles, exact aspects.", "operationId": "calculate_natal_chart", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NatalRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AstrologyNatalResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/astrology/transits": { "post": { "summary": "Transits", "description": "Transiting positions at ``target_datetime`` + aspects to the natal\npoints, with applying / separating and exact orbs.", "operationId": "get_transits_and_aspects", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransitsRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AstrologyTransitsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/astrology/synastry": { "post": { "summary": "Synastry", "description": "Inter-chart aspects between two people + house overlays.", "operationId": "calculate_synastry", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SynastryRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AstrologySynastryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/astrology/resolve-place": { "post": { "summary": "Resolve Place", "description": "Place name -> coordinates + IANA timezone, and (optionally) a naive\nlocal birth time -> tz-aware ``birth_datetime`` with the historically\ncorrect UTC offset. Lets an agent go from \"Warsaw, 14:30\" to a valid\nnatal request without guessing coordinates or DST rules.", "operationId": "resolve_birth_place", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvePlaceRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AstrologyResolvePlaceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "AstroAngle": { "properties": { "sign": { "type": "string", "title": "Sign" }, "degree": { "type": "number", "title": "Degree" }, "absolute_longitude": { "type": "number", "title": "Absolute Longitude" } }, "type": "object", "required": [ "sign", "degree", "absolute_longitude" ], "title": "AstroAngle" }, "AstroAngles": { "properties": { "ascendant": { "$ref": "#/components/schemas/AstroAngle" }, "midheaven": { "$ref": "#/components/schemas/AstroAngle" }, "descendant": { "$ref": "#/components/schemas/AstroAngle" }, "imum_coeli": { "$ref": "#/components/schemas/AstroAngle" } }, "type": "object", "required": [ "ascendant", "midheaven", "descendant", "imum_coeli" ], "title": "AstroAngles" }, "AstroChartInputEcho": { "properties": { "birth_datetime_utc": { "type": "string", "title": "Birth Datetime Utc" }, "latitude": { "type": "number", "title": "Latitude" }, "longitude": { "type": "number", "title": "Longitude" }, "house_system": { "type": "string", "title": "House System" } }, "type": "object", "required": [ "birth_datetime_utc", "latitude", "longitude", "house_system" ], "title": "AstroChartInputEcho" }, "AstroHouse": { "properties": { "house": { "type": "integer", "title": "House" }, "sign": { "type": "string", "title": "Sign" }, "degree": { "type": "number", "title": "Degree" }, "absolute_longitude": { "type": "number", "title": "Absolute Longitude" } }, "type": "object", "required": [ "house", "sign", "degree", "absolute_longitude" ], "title": "AstroHouse" }, "AstroHouseOverlayItem": { "properties": { "planet": { "type": "string", "title": "Planet" }, "house": { "type": "integer", "title": "House" } }, "type": "object", "required": [ "planet", "house" ], "title": "AstroHouseOverlayItem" }, "AstroHouseOverlays": { "properties": { "a_in_b_houses": { "items": { "$ref": "#/components/schemas/AstroHouseOverlayItem" }, "type": "array", "title": "A In B Houses" }, "b_in_a_houses": { "items": { "$ref": "#/components/schemas/AstroHouseOverlayItem" }, "type": "array", "title": "B In A Houses" } }, "type": "object", "required": [ "a_in_b_houses", "b_in_a_houses" ], "title": "AstroHouseOverlays" }, "AstroMeta": { "properties": { "engine": { "type": "string", "title": "Engine" }, "zodiac": { "type": "string", "title": "Zodiac" }, "house_system": { "type": "string", "title": "House System" }, "orbs": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Orbs" }, "time_resolution": { "type": "string", "title": "Time Resolution" }, "points": { "items": { "type": "string" }, "type": "array", "title": "Points" } }, "additionalProperties": true, "type": "object", "required": [ "engine", "zodiac", "house_system", "orbs", "time_resolution", "points" ], "title": "AstroMeta" }, "AstroNatalAspect": { "properties": { "point_a": { "type": "string", "title": "Point A" }, "point_b": { "type": "string", "title": "Point B" }, "aspect": { "type": "string", "title": "Aspect" }, "exact_degrees": { "type": "integer", "title": "Exact Degrees" }, "orb": { "type": "number", "title": "Orb" }, "movement": { "type": "string", "title": "Movement" } }, "type": "object", "required": [ "point_a", "point_b", "aspect", "exact_degrees", "orb", "movement" ], "title": "AstroNatalAspect" }, "AstroPoint": { "properties": { "name": { "type": "string", "title": "Name" }, "sign": { "type": "string", "title": "Sign" }, "degree": { "type": "number", "title": "Degree" }, "absolute_longitude": { "type": "number", "title": "Absolute Longitude" }, "house": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "House" }, "retrograde": { "type": "boolean", "title": "Retrograde" }, "speed": { "type": "number", "title": "Speed" }, "declination": { "type": "number", "title": "Declination" } }, "type": "object", "required": [ "name", "sign", "degree", "absolute_longitude", "retrograde", "speed", "declination" ], "title": "AstroPoint" }, "AstroSynastryAspect": { "properties": { "point_a": { "type": "string", "title": "Point A" }, "point_b": { "type": "string", "title": "Point B" }, "aspect": { "type": "string", "title": "Aspect" }, "exact_degrees": { "type": "integer", "title": "Exact Degrees" }, "orb": { "type": "number", "title": "Orb" } }, "type": "object", "required": [ "point_a", "point_b", "aspect", "exact_degrees", "orb" ], "title": "AstroSynastryAspect" }, "AstroTransitAspect": { "properties": { "transiting": { "type": "string", "title": "Transiting" }, "natal": { "type": "string", "title": "Natal" }, "aspect": { "type": "string", "title": "Aspect" }, "exact_degrees": { "type": "integer", "title": "Exact Degrees" }, "orb": { "type": "number", "title": "Orb" }, "movement": { "type": "string", "title": "Movement" } }, "type": "object", "required": [ "transiting", "natal", "aspect", "exact_degrees", "orb", "movement" ], "title": "AstroTransitAspect" }, "AstroTransitingPoint": { "properties": { "name": { "type": "string", "title": "Name" }, "sign": { "type": "string", "title": "Sign" }, "degree": { "type": "number", "title": "Degree" }, "absolute_longitude": { "type": "number", "title": "Absolute Longitude" }, "retrograde": { "type": "boolean", "title": "Retrograde" }, "speed": { "type": "number", "title": "Speed" }, "declination": { "type": "number", "title": "Declination" }, "natal_house": { "type": "integer", "title": "Natal House" } }, "type": "object", "required": [ "name", "sign", "degree", "absolute_longitude", "retrograde", "speed", "declination", "natal_house" ], "title": "AstroTransitingPoint" }, "AstrologyNatalResponse": { "properties": { "input": { "$ref": "#/components/schemas/AstroChartInputEcho" }, "planets": { "items": { "$ref": "#/components/schemas/AstroPoint" }, "type": "array", "title": "Planets" }, "houses": { "items": { "$ref": "#/components/schemas/AstroHouse" }, "type": "array", "title": "Houses" }, "angles": { "$ref": "#/components/schemas/AstroAngles" }, "aspects": { "items": { "$ref": "#/components/schemas/AstroNatalAspect" }, "type": "array", "title": "Aspects" }, "meta": { "$ref": "#/components/schemas/AstroMeta" } }, "type": "object", "required": [ "input", "planets", "houses", "angles", "aspects", "meta" ], "title": "AstrologyNatalResponse" }, "AstrologyResolvePlaceResponse": { "properties": { "query": { "type": "string", "title": "Query" }, "display_name": { "type": "string", "title": "Display Name" }, "latitude": { "type": "number", "title": "Latitude" }, "longitude": { "type": "number", "title": "Longitude" }, "timezone": { "type": "string", "title": "Timezone" }, "local_datetime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Local Datetime" }, "utc_offset": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Utc Offset" }, "birth_datetime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Birth Datetime" }, "birth_datetime_utc": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Birth Datetime Utc" }, "time_assumed_noon": { "type": "boolean", "title": "Time Assumed Noon", "default": false }, "local_time_ambiguity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Local Time Ambiguity" }, "age_years": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Age Years" }, "source": { "type": "string", "title": "Source" } }, "type": "object", "required": [ "query", "display_name", "latitude", "longitude", "timezone", "source" ], "title": "AstrologyResolvePlaceResponse", "description": "Place name (+ optional naive local time) -> coordinates, IANA zone and\na ready-to-use tz-aware ``birth_datetime`` for the natal endpoints." }, "AstrologySynastryResponse": { "properties": { "person_a": { "$ref": "#/components/schemas/AstrologyNatalResponse" }, "person_b": { "$ref": "#/components/schemas/AstrologyNatalResponse" }, "inter_aspects": { "items": { "$ref": "#/components/schemas/AstroSynastryAspect" }, "type": "array", "title": "Inter Aspects" }, "house_overlays": { "$ref": "#/components/schemas/AstroHouseOverlays" }, "meta": { "$ref": "#/components/schemas/AstroMeta" } }, "type": "object", "required": [ "person_a", "person_b", "inter_aspects", "house_overlays", "meta" ], "title": "AstrologySynastryResponse" }, "AstrologyTransitsResponse": { "properties": { "natal": { "$ref": "#/components/schemas/AstrologyNatalResponse" }, "target_datetime_utc": { "type": "string", "title": "Target Datetime Utc" }, "transiting_planets": { "items": { "$ref": "#/components/schemas/AstroTransitingPoint" }, "type": "array", "title": "Transiting Planets" }, "aspects_to_natal": { "items": { "$ref": "#/components/schemas/AstroTransitAspect" }, "type": "array", "title": "Aspects To Natal" }, "meta": { "$ref": "#/components/schemas/AstroMeta" } }, "type": "object", "required": [ "natal", "target_datetime_utc", "transiting_planets", "aspects_to_natal", "meta" ], "title": "AstrologyTransitsResponse" }, "ChartInputRequest": { "properties": { "birth_datetime": { "type": "string", "title": "Birth Datetime", "description": "ISO-8601 datetime WITH timezone, e.g. '1990-05-17T14:30:00Z' or '1990-05-17T17:30:00+03:00'. Naive values are rejected." }, "latitude": { "type": "number", "maximum": 90.0, "minimum": -90.0, "title": "Latitude", "description": "Birth latitude, degrees" }, "longitude": { "type": "number", "maximum": 180.0, "minimum": -180.0, "title": "Longitude", "description": "Birth longitude, degrees" }, "house_system": { "type": "string", "title": "House System", "description": "House system: one of ['alcabitius', 'campanus', 'equal', 'koch', 'morinus', 'placidus', 'porphyry', 'regiomontanus', 'topocentric', 'whole_sign']", "default": "placidus" } }, "type": "object", "required": [ "birth_datetime", "latitude", "longitude" ], "title": "ChartInputRequest", "description": "One person's birth data." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "NatalRequest": { "properties": { "birth_datetime": { "type": "string", "title": "Birth Datetime", "description": "ISO-8601 datetime WITH timezone, e.g. '1990-05-17T14:30:00Z' or '1990-05-17T17:30:00+03:00'. Naive values are rejected." }, "latitude": { "type": "number", "maximum": 90.0, "minimum": -90.0, "title": "Latitude", "description": "Birth latitude, degrees" }, "longitude": { "type": "number", "maximum": 180.0, "minimum": -180.0, "title": "Longitude", "description": "Birth longitude, degrees" }, "house_system": { "type": "string", "title": "House System", "description": "House system: one of ['alcabitius', 'campanus', 'equal', 'koch', 'morinus', 'placidus', 'porphyry', 'regiomontanus', 'topocentric', 'whole_sign']", "default": "placidus" }, "include_minor_aspects": { "type": "boolean", "title": "Include Minor Aspects", "description": "Also report semi-sextile / semi-square / quintile / sesquiquadrate / biquintile / quincunx with tight orbs", "default": false } }, "type": "object", "required": [ "birth_datetime", "latitude", "longitude" ], "title": "NatalRequest" }, "ResolvePlaceRequest": { "properties": { "place": { "type": "string", "maxLength": 200, "minLength": 2, "title": "Place", "description": "Free-text place of birth, e.g. 'Warsaw, Poland' or 'Варшава'" }, "local_datetime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Local Datetime", "description": "Local wall-clock birth time WITHOUT an offset: 'YYYY-MM-DDTHH:MM[:SS]' or 'YYYY-MM-DD' (date only = 12:00 assumed). The offset is derived from the place's IANA zone, including historical DST." } }, "type": "object", "required": [ "place" ], "title": "ResolvePlaceRequest" }, "SynastryRequest": { "properties": { "person_a": { "$ref": "#/components/schemas/ChartInputRequest" }, "person_b": { "$ref": "#/components/schemas/ChartInputRequest" }, "include_minor_aspects": { "type": "boolean", "title": "Include Minor Aspects", "default": false } }, "type": "object", "required": [ "person_a", "person_b" ], "title": "SynastryRequest" }, "TransitsRequest": { "properties": { "natal": { "$ref": "#/components/schemas/ChartInputRequest" }, "target_datetime": { "type": "string", "title": "Target Datetime", "description": "ISO-8601 datetime WITH timezone, e.g. '1990-05-17T14:30:00Z' or '1990-05-17T17:30:00+03:00'. Naive values are rejected." }, "include_minor_aspects": { "type": "boolean", "title": "Include Minor Aspects", "default": false } }, "type": "object", "required": [ "natal", "target_datetime" ], "title": "TransitsRequest" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } } }, "security": [ { "ApiKeyAuth": [] } ] }