{"openapi":"3.1.0","info":{"title":"NatalChart.AI API","version":"1.0.0","description":"Swiss Ephemeris astrology calculations as JSON: natal charts, transits, synastry and solar returns. Tropical zodiac, Placidus houses, the five major aspects. No generated text and no AI calls. Free: 10 requests a day. API Pro: 1000 requests a day for $6.99 a month. Request bodies are never stored.","termsOfService":"https://www.natalchart.ai/terms","contact":{"name":"NatalChart.AI","url":"https://www.natalchart.ai/developers","email":"contact@natalchart.ai"}},"servers":[{"url":"https://api.natalchart.ai"}],"security":[{"apiKey":[]}],"paths":{"/v1/chart/short":{"post":{"summary":"The short chart: Sun, Moon and Ascendant with degrees, every body's sign, retrograde bodies, dominant element and quality.","tags":["Free and Pro"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["birth"],"properties":{"birth":{"$ref":"#/components/schemas/Birth"}}}}}},"responses":{"200":{"description":"The calculation, as JSON.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds of the next 00:00 UTC."}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/chart/full":{"post":{"summary":"The full chart: every body with longitude, sign, degree, speed, retrograde flag and house; the angles; twelve Placidus cusps; the aspects with orbs; element and quality balance; fixed-star contacts.","tags":["Free and Pro"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["birth"],"properties":{"birth":{"$ref":"#/components/schemas/Birth"}}}}}},"responses":{"200":{"description":"The calculation, as JSON.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds of the next 00:00 UTC."}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/chart/planets":{"post":{"summary":"Bodies only: longitude, sign, degree within the sign, daily speed, retrograde flag, house.","tags":["Free and Pro"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["birth"],"properties":{"birth":{"$ref":"#/components/schemas/Birth"}}}}}},"responses":{"200":{"description":"The calculation, as JSON.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds of the next 00:00 UTC."}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/chart/angles":{"post":{"summary":"Ascendant, Midheaven, Vertex and Part of Fortune.","tags":["Free and Pro"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["birth"],"properties":{"birth":{"$ref":"#/components/schemas/Birth"}}}}}},"responses":{"200":{"description":"The calculation, as JSON.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds of the next 00:00 UTC."}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/chart/houses":{"post":{"summary":"The twelve Placidus house cusps.","tags":["Free and Pro"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["birth"],"properties":{"birth":{"$ref":"#/components/schemas/Birth"}}}}}},"responses":{"200":{"description":"The calculation, as JSON.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds of the next 00:00 UTC."}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/chart/aspects":{"post":{"summary":"The five major aspects between the bodies, each with its angle and orb, and the orb table used.","tags":["Free and Pro"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["birth"],"properties":{"birth":{"$ref":"#/components/schemas/Birth"}}}}}},"responses":{"200":{"description":"The calculation, as JSON.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds of the next 00:00 UTC."}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/chart/elements":{"post":{"summary":"Element and quality balance, with the dominant of each.","tags":["Free and Pro"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["birth"],"properties":{"birth":{"$ref":"#/components/schemas/Birth"}}}}}},"responses":{"200":{"description":"The calculation, as JSON.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds of the next 00:00 UTC."}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/chart/fixed-stars":{"post":{"summary":"Fixed-star conjunctions to the natal bodies within 1.5 degrees.","tags":["Free and Pro"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["birth"],"properties":{"birth":{"$ref":"#/components/schemas/Birth"}}}}}},"responses":{"200":{"description":"The calculation, as JSON.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds of the next 00:00 UTC."}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/horoscope/daily":{"post":{"summary":"The calculated day: the sky at noon UTC, the Moon's phase, the sky events of the coming week and, with birth data, every transit to the natal chart with its orb. No generated text.","tags":["Free and Pro"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"birth":{"$ref":"#/components/schemas/Birth"},"date":{"type":"string","format":"date","description":"The day to compute, today (UTC) by default."}}}}}},"responses":{"200":{"description":"The calculation, as JSON.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds of the next 00:00 UTC."}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/sky":{"get":{"summary":"Planetary positions, Moon phase and the coming week's sky events for a date (?date=YYYY-MM-DD, today by default).","tags":["Free and Pro"],"parameters":[{"name":"date","in":"query","required":false,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"The calculation, as JSON.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds of the next 00:00 UTC."}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/usage":{"get":{"summary":"Your plan, today's count and when the pool refills. Costs nothing.","tags":["Free and Pro"],"responses":{"200":{"description":"The calculation, as JSON.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds of the next 00:00 UTC."}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/transits":{"post":{"summary":"Every transit event in a window of up to 92 days: exact transit-to-natal aspects by date, sign ingresses and stations.","tags":["API Pro"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["birth"],"properties":{"birth":{"$ref":"#/components/schemas/Birth"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date","description":"At most 92 days after from; 30 days by default."}}}}}},"responses":{"200":{"description":"The calculation, as JSON.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds of the next 00:00 UTC."}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/synastry":{"post":{"summary":"Two charts compared: inter-chart aspects with orbs, house overlays both ways and a score per life sphere.","tags":["API Pro"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["personA","personB"],"properties":{"personA":{"$ref":"#/components/schemas/Birth"},"personB":{"$ref":"#/components/schemas/Birth"}}}}}},"responses":{"200":{"description":"The calculation, as JSON.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds of the next 00:00 UTC."}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/solar-return":{"post":{"summary":"The solar return chart for a year, cast for the birth place or another location.","tags":["API Pro"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["birth","year"],"properties":{"birth":{"$ref":"#/components/schemas/Birth"},"year":{"type":"integer","minimum":1900,"maximum":2100},"location":{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"}}}}}}}},"responses":{"200":{"description":"The calculation, as JSON.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch seconds of the next 00:00 UTC."}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Your API key from https://www.natalchart.ai/developers/keys"}},"schemas":{"Birth":{"type":"object","required":["date","latitude","longitude"],"properties":{"date":{"type":"string","format":"date","description":"Birth date, YYYY-MM-DD, 1800 to 2399.","examples":["1991-09-06"]},"time":{"type":["string","null"],"description":"Local birth time, HH:mm, 24-hour. null when unknown: the chart is computed for noon and everything that depends on the time is withheld.","examples":["18:30"]},"latitude":{"type":"number","minimum":-90,"maximum":90,"examples":[50.4501]},"longitude":{"type":"number","minimum":-180,"maximum":180,"examples":[30.5234]},"timezone":{"type":"string","description":"IANA time zone. Leave it out to resolve it from the coordinates; historical daylight-saving rules are applied to the date.","examples":["Europe/Kyiv"]}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["missing_api_key","invalid_api_key","invalid_request","plan_required","daily_limit_reached","not_found","internal_error"]},"message":{"type":"string"},"details":{},"docs":{"type":"string"}}}}}},"responses":{"Error":{"description":"An error, always in this shape.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}