{ "openapi": "3.1.0", "info": { "title": "AstroNest Developer API", "version": "1.0.0", "summary": "Vedic (Jyotiṣa) chart computation and corpus-grounded readings.", "description": "**Ephemeris built in.** Raw positions (Sun to Pluto, mean and true nodes), ascendant and house cusps, ayanamsa values, sunrise and sunset, and position series come from AstroNest’s own NASA JPL DE440 engine, on the same key and credits as the readings: no Swiss Ephemeris licence or second ephemeris API is needed. Coverage 1800–2149 UTC; asteroids and fixed stars are not covered.\n\nStateless: every request carries its inputs inline (birth data, or a moment and place for the Ephemeris operations) and nothing is stored. Responses carry qualitative confidence, never raw scores, rule identifiers or internal methodology.\n\n**Credits.** Every successful (2xx) call spends a fixed number of credits (`x-credits` on each operation), with two exceptions for the Ephemeris operations: positions, angles, ayanamsa and sunrise cost 0.1 credit each, billed as 1 credit per started block of 10 calls per account (`x-billing`), and `/v1/ephemeris/series` spends 1 credit per started 100 points. Non-2xx responses are not charged. Every account gets 100 free live credits once, valid for 60 days from its first live key (they do not renew), spent first; beyond that, prepaid packs bought in the developer portal (Starter 1,000 / $49, Builder 5,000 / $199, Growth 15,000 / $499). Paid credits do not expire. All keys on an account share one balance.\n\n**Sandbox keys** (`astro_sandbox_…`) are free, with no time limit: the request is validated exactly as in live, then a fixed sample response is returned (the example request on each operation) with `sandbox: true`, `usage.units_charged: 0` and an `X-AstroNest-Sandbox: true` header. Your birth data is checked but not used. Use a live key (`astro_live_…`) for real readings.\n\n**Limits.** 120 requests a minute per account, and 2 at once (5 after any purchase). Live keys and purchases require accepting the beta terms at https://www.astronest.ai/developers#terms and a verified email address.\n\n**Keys are secret.** Call the API from your server, never from a browser: the API sends no CORS headers.\n\nSymbolic interpretation only. Not medical, legal, financial, or psychological advice.", "termsOfService": "https://www.astronest.ai/developers#terms", "contact": { "name": "AstroNest developer support", "url": "https://www.astronest.ai/developer#support" }, "license": { "name": "Proprietary. Use is governed by the AstroNest Developer API beta terms.", "url": "https://www.astronest.ai/developers#terms" } }, "servers": [ { "url": "https://www.astronest.ai/api/developer", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Calculation", "description": "Deterministic computation. No language model is called." }, { "name": "Interpretation", "description": "Deterministic readings over the classical corpus. No language model is called." }, { "name": "Narrated", "description": "Readings voiced by a language model, grounded in the deterministic verdict. Slower (tens of seconds)." }, { "name": "Ephemeris", "description": "Raw astronomical positions from AstroNest’s own JPL DE440 engine: no Swiss Ephemeris licence or other astrology API needed. Deterministic, about a millisecond per position, no language model. One key scope (`ephemeris`) covers all five operations." } ], "paths": { "/v1/chart": { "post": { "operationId": "getChart", "tags": [ "Calculation" ], "summary": "Natal chart", "description": "Sidereal (Lahiri) chart: ascendant, the nine grahas, twelve houses, yogas and the Vimśottarī daśā. A modern Western block is added unless `western` is false. With `location`, also astrocartography lines at that place and the chart's own frame relocated there.", "x-credits": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "birthData" ], "properties": { "birthData": { "$ref": "#/components/schemas/BirthData", "description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude." }, "includeDasha": { "type": "boolean", "default": true, "description": "Include the Vimśottarī daśā periods in the chart response. Default true." }, "western": { "type": "boolean", "default": true, "description": "Set false to omit the modern Western block." }, "location": { "$ref": "#/components/schemas/Location" } } }, "example": { "birthData": { "date": "1990-05-12", "time": "14:35", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209 } } } } }, "responses": { "200": { "description": "Chart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChartResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/CreditsExhausted" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/ConcurrencyLimit" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/dasha": { "post": { "operationId": "getDasha", "tags": [ "Calculation" ], "summary": "Vimśottarī daśā timeline", "x-credits": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "birthData" ], "properties": { "birthData": { "$ref": "#/components/schemas/BirthData", "description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude." } } }, "example": { "birthData": { "date": "1990-05-12", "time": "14:35", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209 } } } } }, "responses": { "200": { "description": "Daśā timeline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashaResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/CreditsExhausted" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/ConcurrencyLimit" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/guidance": { "post": { "operationId": "getGuidance", "tags": [ "Interpretation" ], "summary": "Lifestyle guidance for the running daśā periods", "description": "Plain-language guidance cards for each running daśā level (mahādaśā, antardaśā, …) at `referenceDate` (default: now).", "x-credits": 3, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "birthData" ], "properties": { "birthData": { "$ref": "#/components/schemas/BirthData", "description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude." }, "referenceDate": { "type": "string", "description": "ISO date or datetime. Defaults to now." } } }, "example": { "birthData": { "date": "1990-05-12", "time": "14:35", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209 } } } } }, "responses": { "200": { "description": "Guidance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuidanceResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/CreditsExhausted" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/ConcurrencyLimit" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/interpret": { "post": { "operationId": "interpretDomain", "tags": [ "Interpretation" ], "summary": "Domain reading", "description": "Deterministic reading of one life domain: verdict, supporting and cautionary factors, timing windows, method agreement and the weighed corpus position. No language model is called.", "x-credits": 5, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "birthData", "domain" ], "properties": { "birthData": { "$ref": "#/components/schemas/BirthData", "description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude." }, "domain": { "$ref": "#/components/schemas/Domain", "description": "Life area to read, e.g. career, marriage, finance or health." } } }, "example": { "birthData": { "date": "1990-05-12", "time": "14:35", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209 }, "domain": "career" } } } }, "responses": { "200": { "description": "Reading", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterpretResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/CreditsExhausted" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/ConcurrencyLimit" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/compatibility": { "post": { "operationId": "getCompatibility", "tags": [ "Interpretation" ], "summary": "Compatibility of two charts", "description": "Computes both charts and reads them together. Each partner object is a BirthData object plus optional `name` and `gender`.", "x-credits": 12, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "a", "b" ], "properties": { "a": { "$ref": "#/components/schemas/Partner", "description": "First partner: birth data plus optional name and gender." }, "b": { "$ref": "#/components/schemas/Partner", "description": "Second partner: birth data plus optional name and gender." }, "referenceDateIso": { "type": "string", "description": "ISO date the reading is anchored to. Defaults to now." } } }, "example": { "a": { "date": "1990-05-12", "time": "14:35", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209, "name": "A" }, "b": { "date": "1991-11-03", "time": "06:10", "timezone": "Asia/Kolkata", "latitude": 19.076, "longitude": 72.8777, "name": "B" } } } } }, "responses": { "200": { "description": "Compatibility reading", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatibilityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/CreditsExhausted" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/ConcurrencyLimit" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/muhurta": { "post": { "operationId": "findMuhurta", "tags": [ "Interpretation" ], "summary": "Auspicious windows (muhūrta) in a date range", "description": "Scans each day in the range and ranks windows for the subject. The pañcāṅga is computed for `eventPlace`, never defaulted to the birthplace.", "x-credits": 10, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "subject", "eventPlace", "rangeStart", "rangeEnd" ], "properties": { "subject": { "$ref": "#/components/schemas/BirthData", "description": "Birth data of the person the event is for; windows are ranked against their chart." }, "subjectName": { "type": "string", "description": "Optional name of the subject, used only in the response text." }, "eventPlace": { "type": "object", "required": [ "latitude", "longitude", "timezone" ], "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "timezone": { "type": "string", "description": "IANA timezone" }, "label": { "type": "string" } }, "description": "Where the event will happen: latitude, longitude and IANA timezone. The pañcāṅga is computed here, never at the birthplace." }, "rangeStart": { "type": "string", "format": "date", "description": "First date to search, YYYY-MM-DD." }, "rangeEnd": { "type": "string", "format": "date", "description": "Last date to search, YYYY-MM-DD." }, "eventId": { "type": "string", "description": "Event type identifier, if known." }, "freeText": { "type": "string", "description": "The event described in words, when there is no eventId." }, "timeOfDay": { "type": "string", "description": "Local time (HH:MM) at which each day is evaluated. Default: local sunrise." }, "topN": { "type": "integer", "minimum": 1, "description": "How many ranked windows to return. Default 5." } } }, "example": { "subject": { "date": "1990-05-12", "time": "14:35", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209 }, "eventPlace": { "latitude": 19.076, "longitude": 72.8777, "timezone": "Asia/Kolkata", "label": "Mumbai" }, "freeText": "signing a lease", "rangeStart": "2026-11-01", "rangeEnd": "2026-11-15" } } } }, "responses": { "200": { "description": "Ranked windows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MuhurtaResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/CreditsExhausted" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/ConcurrencyLimit" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/forecast": { "post": { "operationId": "getForecast", "tags": [ "Narrated" ], "summary": "Forward-looking reading for a question", "description": "The interpret verdict for `domain`, voiced as a narrative answer to `question` by a language model grounded in the classical statements for the domain. Expect tens of seconds; set a client timeout of at least 90 s.", "x-credits": 8, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "birthData", "domain", "question" ], "properties": { "birthData": { "$ref": "#/components/schemas/BirthData", "description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude." }, "domain": { "$ref": "#/components/schemas/Domain", "description": "Life area the question is about, e.g. career, marriage, finance or health." }, "question": { "type": "string", "minLength": 1, "description": "The question in plain language, e.g. \"What does the next year hold for my career?\"" } } }, "example": { "birthData": { "date": "1990-05-12", "time": "14:35", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209 }, "domain": "career", "question": "How will the next year unfold for my work?" } } } }, "responses": { "200": { "description": "Forecast", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForecastResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/CreditsExhausted" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/ConcurrencyLimit" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/NarrationFailed" } } } }, "/v1/timing/resolve": { "post": { "operationId": "resolveTiming", "tags": [ "Narrated" ], "summary": "Decision timing", "description": "Like forecast, for a decision question, optionally anchored to `targetDate` or `dateRange`. Expect tens of seconds.", "x-credits": 7, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "birthData", "domain", "question" ], "properties": { "birthData": { "$ref": "#/components/schemas/BirthData", "description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude." }, "domain": { "$ref": "#/components/schemas/Domain", "description": "Life area the decision is about, e.g. career, marriage, finance or health." }, "question": { "type": "string", "minLength": 1, "description": "The decision question in plain language, e.g. \"Is this a good time to change jobs?\"" }, "targetDate": { "type": "string", "format": "date", "description": "Optional date the decision is about, YYYY-MM-DD." }, "dateRange": { "type": "object", "required": [ "start", "end" ], "properties": { "start": { "type": "string", "format": "date" }, "end": { "type": "string", "format": "date" } }, "description": "Optional period the decision is about: start and end dates, YYYY-MM-DD." } } }, "example": { "birthData": { "date": "1990-05-12", "time": "14:35", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209 }, "domain": "career", "question": "Should I accept the offer?", "targetDate": "2026-11-15" } } } }, "responses": { "200": { "description": "Timing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/CreditsExhausted" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/ConcurrencyLimit" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/NarrationFailed" } } } }, "/v1/ephemeris/positions": { "post": { "operationId": "getEphemerisPositions", "tags": [ "Ephemeris" ], "summary": "Positions at a moment", "description": "Sun, Moon, planets and lunar nodes at one moment: longitude, latitude, distance, speed and retrograde flag, with sign, and nakṣatra and pada when sidereal. `equatorial: true` adds apparent right ascension and declination.", "x-credits": 0.1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "datetime" ], "properties": { "datetime": { "$ref": "#/components/schemas/EphemerisDateTime" }, "bodies": { "type": "array", "items": { "$ref": "#/components/schemas/EphemerisBody" }, "description": "Default: all twelve." }, "zodiac": { "$ref": "#/components/schemas/Zodiac", "description": "sidereal (default) or tropical." }, "ayanamsa": { "$ref": "#/components/schemas/Ayanamsa" }, "equatorial": { "type": "boolean", "default": false, "description": "Also return apparent right ascension and declination. Default false." } } }, "example": { "datetime": "2026-10-06T06:00:00Z", "bodies": [ "Sun", "Moon", "Mars", "Jupiter", "Saturn", "TrueNode" ], "zodiac": "sidereal", "ayanamsa": "lahiri" } } } }, "responses": { "200": { "description": "Positions at a moment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EphemerisPositionsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/CreditsExhausted" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/ConcurrencyLimit" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-billing": "1 credit per started block of 10 calls, counted per account across positions, angles, ayanamsa and sunrise (the call that opens a block is charged 1 credit and reports usage.units_charged 1; the next nine report 0). Failed calls do not count." } }, "/v1/ephemeris/angles": { "post": { "operationId": "getEphemerisAngles", "tags": [ "Ephemeris" ], "summary": "Ascendant, MC and house cusps", "description": "Ascendant, midheaven and twelve cusps for a moment and place. Placidus is undefined beyond the polar circles at some moments; the call then returns 422 houses_undefined_at_latitude.", "x-credits": 0.1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "datetime", "latitude", "longitude" ], "properties": { "datetime": { "$ref": "#/components/schemas/EphemerisDateTime" }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Geographic latitude in decimal degrees, north positive." }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "East positive." }, "houseSystem": { "type": "string", "enum": [ "whole_sign", "equal", "placidus" ], "default": "whole_sign", "description": "House system for the cusps: whole_sign (default), equal or placidus." }, "zodiac": { "$ref": "#/components/schemas/Zodiac", "description": "sidereal (default) or tropical." }, "ayanamsa": { "$ref": "#/components/schemas/Ayanamsa" } } }, "example": { "datetime": "1990-05-12T14:35:00+05:30", "latitude": 28.6139, "longitude": 77.209, "houseSystem": "placidus" } } } }, "responses": { "200": { "description": "Ascendant, MC and house cusps", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EphemerisAnglesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/CreditsExhausted" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/ConcurrencyLimit" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-billing": "1 credit per started block of 10 calls, counted per account across positions, angles, ayanamsa and sunrise (the call that opens a block is charged 1 credit and reports usage.units_charged 1; the next nine report 0). Failed calls do not count." } }, "/v1/ephemeris/ayanamsa": { "post": { "operationId": "getEphemerisAyanamsa", "tags": [ "Ephemeris" ], "summary": "Ayanamsa values", "description": "Lahiri, Raman, Krishnamurti and Fagan–Bradley (mean, without nutation) at a moment.", "x-credits": 0.1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "datetime" ], "properties": { "datetime": { "$ref": "#/components/schemas/EphemerisDateTime" } } }, "example": { "datetime": "2026-10-06T00:00:00Z" } } } }, "responses": { "200": { "description": "Ayanamsa values", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EphemerisAyanamsaResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/CreditsExhausted" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/ConcurrencyLimit" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-billing": "1 credit per started block of 10 calls, counted per account across positions, angles, ayanamsa and sunrise (the call that opens a block is charged 1 credit and reports usage.units_charged 1; the next nine report 0). Failed calls do not count." } }, "/v1/ephemeris/sunrise": { "post": { "operationId": "getEphemerisSunrise", "tags": [ "Ephemeris" ], "summary": "Sunrise and sunset", "description": "Sunrise, sunset and the next sunrise for a local date and place: upper limb at the sea-level horizon with 36.6′ refraction. The Vedic day runs from sunrise to the next sunrise.", "x-credits": 0.1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "date", "timezone", "latitude", "longitude" ], "properties": { "date": { "type": "string", "format": "date", "description": "Local calendar date, YYYY-MM-DD." }, "timezone": { "type": "string", "description": "IANA name, e.g. Asia/Kolkata. Defines the local day." }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Geographic latitude in decimal degrees, north positive." }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "East positive." } } }, "example": { "date": "2026-10-06", "timezone": "Asia/Kolkata", "latitude": 28.6139, "longitude": 77.209 } } } }, "responses": { "200": { "description": "Sunrise and sunset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EphemerisSunriseResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/CreditsExhausted" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/ConcurrencyLimit" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-billing": "1 credit per started block of 10 calls, counted per account across positions, angles, ayanamsa and sunrise (the call that opens a block is charged 1 credit and reports usage.units_charged 1; the next nine report 0). Failed calls do not count." } }, "/v1/ephemeris/series": { "post": { "operationId": "getEphemerisSeries", "tags": [ "Ephemeris" ], "summary": "Positions over a range", "description": "Positions from start to end (inclusive) every stepMinutes, for transit tables and station finding. At most 1,000 points (too_many_points beyond). **Price: 1 credit per started 100 points** (a 365-point daily table costs 4).", "x-credits": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "start", "end", "stepMinutes" ], "properties": { "start": { "$ref": "#/components/schemas/EphemerisDateTime" }, "end": { "$ref": "#/components/schemas/EphemerisDateTime" }, "stepMinutes": { "type": "integer", "minimum": 1, "maximum": 525600, "description": "Minutes between points (1 to 525,600). At most 1,000 points per call." }, "bodies": { "type": "array", "items": { "$ref": "#/components/schemas/EphemerisBody" }, "description": "Default: all twelve." }, "zodiac": { "$ref": "#/components/schemas/Zodiac", "description": "sidereal (default) or tropical." }, "ayanamsa": { "$ref": "#/components/schemas/Ayanamsa" } } }, "example": { "start": "2026-10-01T00:00:00Z", "end": "2026-10-10T00:00:00Z", "stepMinutes": 1440, "bodies": [ "Mercury", "Venus" ] } } } }, "responses": { "200": { "description": "Positions over a range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EphemerisSeriesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/CreditsExhausted" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/ConcurrencyLimit" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key from the developer portal: `astro_live_<48 hex>` or `astro_sandbox_<48 hex>`." } }, "schemas": { "BirthData": { "type": "object", "required": [ "date", "timezone", "latitude", "longitude" ], "properties": { "date": { "type": "string", "format": "date", "description": "YYYY-MM-DD" }, "time": { "type": "string", "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$", "description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced." }, "timezone": { "type": "string", "description": "IANA timezone of the birthplace, e.g. Asia/Kolkata." }, "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } } }, "Partner": { "allOf": [ { "$ref": "#/components/schemas/BirthData" }, { "type": "object", "properties": { "name": { "type": "string" }, "gender": { "type": "string", "enum": [ "male", "female" ] } } } ] }, "Location": { "type": "object", "description": "Both coordinates or neither: a half-filled location is refused, never defaulted.", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "orbDegrees": { "type": "number", "default": 3, "maximum": 15 } } }, "Domain": { "type": "string", "enum": [ "career", "business", "finance", "children", "property", "education", "travel", "spirituality", "lineage", "reputation", "partnerships", "legal", "family", "marriage", "health" ] }, "Usage": { "type": "object", "required": [ "units_charged", "remaining_credits" ], "properties": { "units_charged": { "type": "integer", "description": "Credits this call spent." }, "remaining_credits": { "type": "integer", "description": "Your one-time free credits left plus the paid balance, after this call." } } }, "Envelope": { "type": "object", "required": [ "requestId", "engineVersion", "timestamp", "usage", "disclaimer" ], "properties": { "requestId": { "type": "string", "description": "Quote this in any support request." }, "engineVersion": { "type": "string", "const": "astro-nest-v1-public" }, "timestamp": { "type": "string", "format": "date-time" }, "usage": { "$ref": "#/components/schemas/Usage" }, "disclaimer": { "type": "string" }, "sandbox": { "type": "boolean", "description": "Present and true only on sandbox-key responses: a fixed sample, not computed from your request." }, "sandboxNote": { "type": "string" }, "domain": { "type": "string" } } }, "Planet": { "type": "object", "properties": { "planet": { "type": "string" }, "sign": { "type": "string" }, "house": { "type": "integer" }, "degree": { "type": "number", "description": "Degree within the sign." }, "longitude": { "type": "number", "description": "Sidereal longitude, 0–360." }, "retrograde": { "type": "boolean" }, "nakshatra": { "type": [ "string", "null" ] }, "pada": { "type": [ "integer", "null" ] }, "dignity": { "type": [ "string", "null" ] } } }, "House": { "type": "object", "properties": { "house": { "type": "integer" }, "sign": { "type": "string" }, "degree": { "type": "number" }, "lord": { "type": "string" } } }, "DashaPeriod": { "type": "object", "properties": { "planet": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" }, "level": { "type": "string", "enum": [ "mahadasha", "antardasha", "pratyantardasha" ] }, "antardashas": { "type": "array", "items": { "$ref": "#/components/schemas/DashaPeriod" } } } }, "CurrentDasha": { "type": [ "object", "null" ], "properties": { "mahadasha": { "type": "string" }, "mahadashaEnd": { "type": "string" }, "antardasha": { "type": [ "string", "null" ] }, "antardashaEnd": { "type": [ "string", "null" ] } } }, "ChartResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "domain": { "type": "string", "const": "core_chart" }, "computationId": { "type": "string", "description": "SHA-256 of the inputs: identical inputs give the same id, and it never exposes the birth data." }, "ascendant": { "type": "object", "properties": { "sign": { "type": "string" }, "degree": { "type": "number" }, "nakshatra": { "type": [ "string", "null" ] } } }, "planets": { "type": "array", "items": { "$ref": "#/components/schemas/Planet" } }, "houses": { "type": "array", "items": { "$ref": "#/components/schemas/House" } }, "aspects": { "type": "array", "description": "The five Ptolemaic majors by degree with orbs — a Western construction, not Vedic graha dṛṣṭi.", "items": { "type": "object", "properties": { "planet1": { "type": "string" }, "planet2": { "type": "string" }, "type": { "type": "string" }, "orb": { "type": "number" }, "applying": { "type": "boolean" } } } }, "yogas": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "dasha": { "type": [ "object", "null" ], "properties": { "current": { "$ref": "#/components/schemas/CurrentDasha" }, "timeline": { "type": "array", "items": { "$ref": "#/components/schemas/DashaPeriod" } } } }, "divisionals": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "western": { "type": "object", "additionalProperties": true, "description": "Modern Western techniques, published alongside the Jyotiṣa engine and not part of it. Every object carries `tradition: \"western\"` and `classical: false`." }, "relocation": { "type": "object", "additionalProperties": true, "description": "Present when `location` was sent: this chart's own frame recomputed for that place." } } } ] }, "DashaResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "domain": { "type": "string", "const": "dasha" }, "computationId": { "type": "string" }, "current": { "$ref": "#/components/schemas/CurrentDasha" }, "timeline": { "type": "array", "items": { "$ref": "#/components/schemas/DashaPeriod" } } } } ] }, "GuidanceCard": { "type": "object", "properties": { "kind": { "type": "string" }, "key": { "type": "string" }, "headline": { "type": "string" }, "because": { "type": "string" }, "do": { "type": "array", "items": { "type": "string" } }, "takeCare": { "type": "array", "items": { "type": "string" } }, "areas": { "type": "array", "items": { "type": "string" } }, "why": { "type": "string" }, "cancelled": { "type": "boolean" } } }, "GuidanceResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "domain": { "type": "string", "const": "lifestyle_guidance" }, "contentVersion": { "type": "string" }, "referenceDate": { "type": "string" }, "levels": { "type": "array", "items": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "chapter", "period", "stretch" ], "description": "chapter = mahādaśā, period = antardaśā, stretch = pratyantardaśā." }, "planet": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" }, "heading": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } }, "cards": { "type": "array", "items": { "$ref": "#/components/schemas/GuidanceCard" } } } } }, "relation": { "oneOf": [ { "$ref": "#/components/schemas/GuidanceCard" }, { "type": "null" } ] }, "formedNotRunning": { "type": "array", "items": { "type": "string" }, "description": "Yogas formed in the chart whose periods are not running now." }, "healthNote": { "type": [ "string", "null" ] } } } ] }, "TimingWindow": { "type": "object", "properties": { "period": { "type": "string" }, "tone": { "type": "string", "enum": [ "favorable", "cautionary", "neutral" ] }, "description": { "type": "string" } } }, "EventTiming": { "type": "object", "properties": { "eventType": { "type": "string" }, "significators": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "occurred_or_overdue", "current", "upcoming", "unknown" ] }, "window": { "type": [ "object", "null" ], "properties": { "ageStart": { "type": "number" }, "ageEnd": { "type": "number" }, "startYear": { "type": "integer" }, "endYear": { "type": "integer" }, "level": { "type": "string" }, "coActivation": { "type": "boolean" } } }, "note": { "type": "string" } } }, "CorpusResolution": { "type": "object", "description": "The weighed position of the classical corpus on this chart, as counts. Never source names on this surface.", "properties": { "positions": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "configuration": { "type": "string" }, "verdict": { "type": [ "string", "null" ], "enum": [ "support", "challenge", "mixed", null ] }, "abstention": { "type": [ "string", "null" ] }, "corroboratingSources": { "type": "integer" }, "dissentingSources": { "type": "integer" }, "withdrawnSources": { "type": "integer" }, "uncheckedExceptions": { "type": "integer" } } } }, "coverage": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "considered": { "type": "integer" }, "matched": { "type": "integer" } } } }, "withheldCount": { "type": "integer" } } }, "ReadingFields": { "type": "object", "properties": { "domain": { "type": "string" }, "confidenceTier": { "type": "string", "enum": [ "high", "medium", "low" ] }, "timingPattern": { "type": "string", "enum": [ "favorable", "cautionary", "mixed", "unclear" ] }, "keyInsights": { "type": "array", "items": { "type": "string" } }, "cautionNotes": { "type": "array", "items": { "type": "string" } }, "timingWindows": { "type": "array", "items": { "$ref": "#/components/schemas/TimingWindow" } }, "practicalContext": { "type": "string" }, "classicalSources": { "type": "array", "items": { "type": "string" }, "description": "Titles of the classical texts the domain is grounded in. Omitted until validated." }, "eventTiming": { "$ref": "#/components/schemas/EventTiming" }, "corpusResolution": { "$ref": "#/components/schemas/CorpusResolution" } } }, "InterpretResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "$ref": "#/components/schemas/ReadingFields" }, { "type": "object", "properties": { "methodAgreement": { "type": "object", "properties": { "methodsConsulted": { "type": "integer" }, "methodsThatSpoke": { "type": "integer" }, "methodsAgreeing": { "type": "integer" }, "verdictContested": { "type": "boolean", "description": "True when the methods read the opposite way to this response's verdict." } } }, "coverage": { "type": "object", "description": "Whether each optional block was computed. `computed_empty` means it ran and found nothing; `failed` means it did not run.", "properties": { "methodAgreement": { "$ref": "#/components/schemas/CoverageState" }, "corpusResolution": { "$ref": "#/components/schemas/CoverageState" }, "classicalSources": { "$ref": "#/components/schemas/CoverageState" }, "eventTiming": { "$ref": "#/components/schemas/CoverageState" } } }, "readingWindow": { "type": "object", "properties": { "referenceDate": { "type": "string", "format": "date" }, "timezone": { "type": "string" } } } } } ] }, "CoverageState": { "type": "string", "enum": [ "present", "computed_empty", "not_covered", "failed" ] }, "ForecastResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "$ref": "#/components/schemas/ReadingFields" }, { "type": "object", "properties": { "summary": { "type": "string", "description": "The narrated answer." }, "directAnswer": { "type": "string" }, "scenarios": { "type": "object", "properties": { "mostLikely": { "type": "string" }, "favorable": { "type": "string" }, "difficult": { "type": "string" } } } } } ] }, "TimingResponse": { "allOf": [ { "$ref": "#/components/schemas/ForecastResponse" }, { "type": "object", "properties": { "decisionQuestion": { "type": "string" }, "exactDateAssessment": { "type": [ "string", "null" ] } } } ] }, "Error": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string", "description": "Machine-readable code." }, "message": { "type": "string" }, "requestId": { "type": [ "string", "null" ], "description": "Null on authentication failures, which are rejected before an id is assigned." }, "statusCode": { "type": "integer" } } }, "CompatibilityResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "compatibility" ], "properties": { "compatibility": { "type": "object", "description": "Both charts read together. Every field is a plain-language reading or a classical count; no internal scores or rule identifiers.", "properties": { "generatedAtIso": { "type": "string" }, "chartA": { "type": "object", "properties": { "name": { "type": "string" }, "birth": { "type": "string" } } }, "chartB": { "type": "object", "properties": { "name": { "type": "string" }, "birth": { "type": "string" } } }, "verdict": { "type": "object", "properties": { "classification": { "type": "string" }, "plainLabel": { "type": "string" }, "governingFactor": { "type": "string" }, "scoreVsAnalysis": { "type": "string" }, "whereAligned": { "type": "string" }, "whereItTakesWork": { "type": "string" }, "plainly": { "type": "string" } } }, "gunaMilan": { "type": "object", "description": "Aṣṭakūṭa (36-point) matching.", "properties": { "totalGunas": { "type": "number" }, "kutas": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "score": { "type": "number" }, "max": { "type": "number" }, "note": { "type": "string" } } } }, "bhakootDosha": { "$ref": "#/components/schemas/Dosha" }, "nadiDosha": { "$ref": "#/components/schemas/Dosha" }, "interpretation": { "type": "string" } } }, "sustainability": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "happiness": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "promise": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "progeny": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "timing": { "type": "object", "additionalProperties": true }, "synastryOverlay": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "synastryCrossTriggers": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "onto": { "type": "string" }, "label": { "type": "string" }, "reason": { "type": "string" }, "valence": { "type": "string" } } } }, "jaimini": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "birthTimeCaveats": { "type": "array", "description": "Whether each lagna sits near a sign boundary, so a small birth-time error would change it.", "items": { "type": "object", "additionalProperties": true } }, "method": { "type": "object", "additionalProperties": true }, "corpusResolution": { "type": "object", "properties": { "a": { "oneOf": [ { "$ref": "#/components/schemas/CorpusResolution" }, { "type": "null" } ] }, "b": { "oneOf": [ { "$ref": "#/components/schemas/CorpusResolution" }, { "type": "null" } ] } } } } } } } ] }, "Dosha": { "type": [ "object", "null" ], "properties": { "present": { "type": "boolean" }, "cancelled": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] } } }, "MuhurtaResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "muhurta" ], "properties": { "muhurta": { "type": "object", "properties": { "event": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "hint": { "type": "string" }, "matchedFromText": { "type": "boolean" }, "freeText": { "type": [ "string", "null" ] } } }, "eventPlaceLabel": { "type": [ "string", "null" ] }, "rangeStart": { "type": "string" }, "rangeEnd": { "type": "string" }, "daysEvaluated": { "type": "integer" }, "windows": { "type": "object", "properties": { "bestSuitability": { "type": "string" }, "suitabilityDistribution": { "type": "object", "additionalProperties": { "type": "integer" } }, "avoidDates": { "type": "array", "items": { "type": "string" } }, "topWindows": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "suitability": { "type": "string", "enum": [ "excellent", "good", "neutral", "poor", "avoid" ] }, "strengthSummary": { "type": "string" }, "keyPositives": { "type": "array", "items": { "type": "string" } }, "keyNegatives": { "type": "array", "items": { "type": "string" } }, "factors": { "type": "array", "items": { "type": "string" } }, "avoidReasons": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "hora": { "type": "object", "properties": { "lord": { "type": "string" }, "favorable": { "type": [ "boolean", "null" ] } } }, "tara": { "type": "object", "properties": { "name": { "type": "string" }, "sentiment": { "type": "string" } } }, "chandraBala": { "type": "string" }, "panchapakshi": { "type": "object", "properties": { "activity": { "type": "string" }, "favorable": { "type": [ "boolean", "null" ] } } }, "combustWarning": { "type": "boolean" } } } } } }, "classicalSources": { "type": "array", "items": { "type": "string" }, "description": "Titles of the muhūrta texts consulted. Titles only." }, "warnings": { "type": "array", "items": { "type": "string" } } } } } } ] }, "EphemerisDateTime": { "type": "string", "format": "date-time", "description": "ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime).", "example": "2026-10-06T06:00:00Z" }, "EphemerisBody": { "type": "string", "enum": [ "Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto", "MeanNode", "TrueNode" ], "description": "MeanNode and TrueNode are Rāhu (mean or true); Ketu is the node + 180°." }, "Zodiac": { "type": "string", "enum": [ "sidereal", "tropical" ], "default": "sidereal" }, "Ayanamsa": { "type": "string", "enum": [ "lahiri", "raman", "krishnamurti", "fagan_bradley" ], "default": "lahiri", "description": "Sidereal only." }, "EphemerisSource": { "type": "object", "properties": { "name": { "type": "string" }, "source": { "type": "string" }, "coverage": { "type": "string" } } }, "Placement": { "type": "object", "properties": { "sign": { "type": "string" }, "signNumber": { "type": "integer", "minimum": 1, "maximum": 12 }, "degreeInSign": { "type": "number" }, "nakshatra": { "type": "string", "description": "Sidereal only." }, "nakshatraNumber": { "type": "integer", "minimum": 1, "maximum": 27 }, "pada": { "type": "integer", "minimum": 1, "maximum": 4 } } }, "ZodiacInfo": { "type": "object", "properties": { "zodiac": { "$ref": "#/components/schemas/Zodiac" }, "ayanamsa": { "$ref": "#/components/schemas/Ayanamsa" }, "ayanamsaValue": { "type": "number", "description": "Degrees; mean ayanamsa at the moment (sidereal only)." } } }, "EphemerisPosition": { "allOf": [ { "$ref": "#/components/schemas/Placement" }, { "type": "object", "properties": { "body": { "$ref": "#/components/schemas/EphemerisBody" }, "longitude": { "type": "number", "description": "Degrees [0, 360) in the requested zodiac." }, "latitude": { "type": "number" }, "distanceAu": { "type": [ "number", "null" ], "description": "Null for the nodes." }, "speed": { "type": "number", "description": "Degrees per day in longitude; negative = retrograde." }, "retrograde": { "type": "boolean" }, "rightAscension": { "type": "number", "description": "With equatorial: true. Apparent, of date, degrees." }, "declination": { "type": "number", "description": "With equatorial: true." } } } ] }, "EphemerisPositionsResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "$ref": "#/components/schemas/ZodiacInfo" }, { "type": "object", "properties": { "datetime": { "type": "string", "format": "date-time" }, "julianDayUT": { "type": "number" }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/EphemerisPosition" } }, "ephemeris": { "$ref": "#/components/schemas/EphemerisSource" } } } ] }, "EphemerisAnglesResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "$ref": "#/components/schemas/ZodiacInfo" }, { "type": "object", "properties": { "datetime": { "type": "string", "format": "date-time" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "houseSystem": { "type": "string", "enum": [ "whole_sign", "equal", "placidus" ] }, "ascendant": { "allOf": [ { "$ref": "#/components/schemas/Placement" }, { "type": "object", "properties": { "longitude": { "type": "number" } } } ] }, "midheaven": { "allOf": [ { "$ref": "#/components/schemas/Placement" }, { "type": "object", "properties": { "longitude": { "type": "number" } } } ] }, "cusps": { "type": "array", "minItems": 12, "maxItems": 12, "items": { "allOf": [ { "$ref": "#/components/schemas/Placement" }, { "type": "object", "properties": { "longitude": { "type": "number" }, "house": { "type": "integer" } } } ] } }, "ephemeris": { "$ref": "#/components/schemas/EphemerisSource" } } } ] }, "EphemerisAyanamsaResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "datetime": { "type": "string", "format": "date-time" }, "note": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": "number" } }, "ephemeris": { "$ref": "#/components/schemas/EphemerisSource" } } } ] }, "EphemerisSunriseResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "timezone": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "convention": { "type": "string" }, "sunrise": { "type": [ "object", "null" ], "properties": { "utc": { "type": "string", "format": "date-time" }, "local": { "type": "string", "description": "HH:MM:SS in the requested timezone" } } }, "sunset": { "type": [ "object", "null" ], "properties": { "utc": { "type": "string", "format": "date-time" }, "local": { "type": "string", "description": "HH:MM:SS in the requested timezone" } } }, "nextSunrise": { "type": [ "object", "null" ], "properties": { "utc": { "type": "string", "format": "date-time" }, "local": { "type": "string", "description": "HH:MM:SS in the requested timezone" } } }, "dayLengthMinutes": { "type": [ "number", "null" ] }, "note": { "type": "string", "description": "Present when the Sun does not rise or set (polar day or night); those fields are null." }, "ephemeris": { "$ref": "#/components/schemas/EphemerisSource" } } } ] }, "EphemerisSeriesResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "$ref": "#/components/schemas/ZodiacInfo" }, { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "stepMinutes": { "type": "integer" }, "pointCount": { "type": "integer" }, "bodies": { "type": "array", "items": { "$ref": "#/components/schemas/EphemerisBody" } }, "points": { "type": "array", "items": { "type": "object", "description": "datetime, plus one key per requested body: longitude, latitude, speed, retrograde and the placement.", "properties": { "datetime": { "type": "string", "format": "date-time" } }, "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/Placement" }, { "type": "object", "properties": { "longitude": { "type": "number" }, "latitude": { "type": "number" }, "speed": { "type": "number" }, "retrograde": { "type": "boolean" } } } ] } } }, "ephemeris": { "$ref": "#/components/schemas/EphemerisSource" } } } ] } }, "responses": { "BadRequest": { "description": "Invalid request. Codes: invalid_json, missing_birthdata, invalid_birthdata, invalid_timezone, invalid_coordinates, missing_required_field, invalid_domain, invalid_reference_date, invalid_range, no_days_evaluable. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "missing_api_key, invalid_api_key, revoked_key or expired_key. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "CreditsExhausted": { "description": "credits_exhausted: the one-time free credits are used or have expired (60 days from the first live key) and the paid balance is too low for this call; buy a credit pack in the developer portal. key_credit_limit_reached: this key has reached the monthly credit limit set on it in the portal (resets on the 1st, UTC). Never charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InsufficientScope": { "description": "insufficient_scope: the key is not scoped for this endpoint. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unprocessable": { "description": "chart_integrity_failed, dasha_failed or guidance_failed: the birth data could not produce a valid result. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ConcurrencyLimit": { "description": "rate_limited (over 120 requests a minute for this account) or concurrency_limit (too many requests at once). Retry-After says when to retry. Not charged.", "headers": { "Retry-After": { "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NarrationFailed": { "description": "narration_failed: the language model did not return a reading. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServerError": { "description": "Our error. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }