Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Asterwise KP API
description: 'B2B astrology and divination API.
Vedic (sidereal) and Western (tropical) astrology, numerology, tarot, crystals, dreams, and
horoscopes. Send birth data, get accurate calculations as structured JSON. 129 endpoints,
118 MCP tools, HMAC-signed responses.
**Get your free API key** · Pricing · Support
---
## Authentication
Add your API key to every request:
```
Authorization: Bearer YOUR_KEY_HERE
```
Get your key at **asterwise.com** — free, no credit card, instant.
---
## Your first call
```bash
curl https://api.asterwise.com/v1/astro/natal \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d ''{
"name": "Arjun Mehta",
"date": "1985-11-12",
"time": "06:45",
"location": "Mumbai"
}''
```
---
## Key concepts
**`location`** — Any city name. Resolved automatically.
**`ayanamsa`** — `lahiri` (default) · `raman` · `kp` · `tropical`
---
500 free calls/month
status.asterwise.com · Error Reference'
contact:
name: Asterwise
url: https://asterwise.com/
license:
name: Commercial
identifier: LicenseRef-Commercial
version: '2026-03-01'
servers:
- url: https://api.asterwise.com
description: Production
tags:
- name: KP
description: Krishnamurti Paddhati — sub-lords, cuspal significations, KP chart, ruling planets.
paths:
/v1/astro/kp/chart:
post:
tags:
- KP
summary: KP Natal Chart
description: 'Computes the KP (Krishnamurti Paddhati) natal chart using Krishnamurti ayanamsa and Placidus house system. Returns planet positions with nakshatra lord and sub-lord, and all 12 house cusps with sub-lords. Planet `house` is the KP (cusp-to-cusp) house: a planet is in house h from cusp h up to, not including, cusp h+1 of the sidereal Placidus cusps, and a planet exactly on a cusp is in the house that cusp starts (no orb before a cusp). `rasi_house` is the whole-sign house from the lagna sign. Inside the polar circles, where Placidus cusps do not exist, the request fails with 422 `validation_error` instead of returning another house system; its `details` item has `type` and `issue` `no_quadrant_houses_at_this_latitude` and `input_format_ok: true` (the input is valid; the sky has no Placidus cusps there). Request JSON follows BirthInput: `name`, `date` (YYYY-MM-DD), `time` (HH:MM, required), either `location` or `latitude`/`longitude`/`timezone`. `ayanamsa` is accepted but ignored: KP always uses the Krishnamurti ayanamsa.'
operationId: get_kp_chart_v1_astro_kp_chart_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/KPBirthRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse_KPChartResponse_'
'401':
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Authorization failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'413':
description: Payload too large
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'502':
description: Upstream provider error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
description: Service unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-subcategory: KP System
security:
- BearerAuth: []
/v1/astro/kp/significators:
post:
tags:
- KP
summary: KP House Significators
description: 'Computes KP house significators for all 12 houses. For each house returns: occupants (cusp-to-cusp), the sign lord of the cusp, planets in the nakshatra of an occupant, and planets in the nakshatra of the sign lord. Krishnamurti ranks them strongest first as: planets in the star of occupants, occupants, planets in the star of the sign lord, the sign lord; `strength_order` lists them in that order. `all_significators` keeps its original order (occupants, sign lord, star of occupants, star of sign lord) and is not a ranking. Planet `house` is the KP (cusp-to-cusp) house: a planet is in house h from cusp h up to, not including, cusp h+1 of the sidereal Placidus cusps, and a planet exactly on a cusp is in the house that cusp starts (no orb before a cusp). `rasi_house` is the whole-sign house from the lagna sign. Inside the polar circles, where Placidus cusps do not exist, the request fails with 422 `validation_error` instead of returning another house system; its `details` item has `type` and `issue` `no_quadrant_houses_at_this_latitude` and `input_format_ok: true` (the input is valid; the sky has no Placidus cusps there). Request JSON follows BirthInput: `name`, `date` (YYYY-MM-DD), `time` (HH:MM, required), either `location` or `latitude`/`longitude`/`timezone`. `ayanamsa` is accepted but ignored: KP always uses the Krishnamurti ayanamsa.'
operationId: get_kp_significators_v1_astro_kp_significators_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/KPBirthRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse_KPSignificatorsResponse_'
'401':
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Authorization failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'413':
description: Payload too large
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'502':
description: Upstream provider error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
description: Service unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-subcategory: KP System
security:
- BearerAuth: []
/v1/astro/kp/ruling-planets:
post:
tags:
- KP
summary: KP Ruling Planets
description: 'Computes KP Ruling Planets at a given moment (no natal birth chart). Request body: `latitude`, `longitude`, optional `target_date`, `target_time`, `target_timezone`. KP takes ruling planets at the moment of judgment, so with no `target_date` and no `target_time` the current instant is used. `target_time` alone means that time today; `target_date` alone means 12:00 on that date. Local date and time are read in `target_timezone`, which defaults to the time zone at the coordinates. `target_utc` and `target_timezone` in the response show the instant and zone used. A date not in the calendar (e.g. 2026-02-30) is rejected with 422 saying it does not exist; dates outside 1800-01-01 to 2099-12-31 are rejected with 422 too. A local time skipped by a daylight-saving change is read with the offset before the change (moved forward by the gap), a repeated time as its first occurrence; `local_time_status` says which applied. Works at every latitude, including inside the polar circles: only the ascendant is used, which needs no house cusps (the day lord still needs a sunrise). Returns day lord, Moon sign/nakshatra/sub lords, ascendant sign/nakshatra/sub lords, and the combined list of ruling planets in priority order.'
operationId: get_kp_ruling_planets_v1_astro_kp_ruling_planets_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/KPRulingPlanetsRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse_KPRulingPlanetsResponse_'
'401':
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Authorization failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'413':
description: Payload too large
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'502':
description: Upstream provider error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
description: Service unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-subcategory: KP System
security:
- BearerAuth: []
components:
schemas:
ErrorCode:
type: string
enum:
- authentication_failed
- api_key_missing
- api_key_not_found
- api_key_revoked
- api_key_invalid
- session_not_found
- session_revoked
- session_expired
- session_required
- email_not_verified
- ip_rate_limit_exceeded
- login_attempts_exceeded
- account_action_limit_exceeded
- burst_limit_exceeded
- monthly_usage_limit_exceeded
- validation_error
- invalid_email
- invalid_request_body
- sun_calculation_failed
- solar_day_out_of_range
- ephemeris_unavailable
- location_required
- geocode_query_too_short
- plan_not_found
- account_not_found
- key_not_found
- subscription_not_found
- city_not_found
- resource_not_found
- ownership_denied
- payment_verification_failed
- order_creation_failed
- already_on_plan
- max_keys_exceeded
- subscription_expired
- payment_provider_unavailable
- payment_request_invalid
- payload_too_large
- email_delivery_failed
- geocode_unavailable
- internal_error
title: ErrorCode
KPBirthRequest:
properties:
location:
anyOf:
- type: string
- type: 'null'
title: Location
description: 'City name to resolve to lat/lon/tz automatically. Example: ''Mumbai'' or ''New Delhi, India''. If provided, latitude, longitude and timezone are not required.'
examples:
- Mumbai
name:
type: string
minLength: 1
title: Name
description: Person name associated with the birth record
default: Chart
examples:
- Arjun Mehta
date:
type: string
title: Date
description: Birth date in YYYY-MM-DD format
examples:
- '1985-11-12'
time:
type: string
title: Time
description: 'Birth time in HH:MM 24-hour format. Required: this endpoint has no sunrise fallback.'
examples:
- 06:45
latitude:
anyOf:
- type: number
maximum: 90.0
minimum: -90.0
- type: 'null'
title: Latitude
description: Latitude. Required if location not provided.
examples:
- 19.055
longitude:
anyOf:
- type: number
maximum: 180.0
minimum: -180.0
- type: 'null'
title: Longitude
description: Longitude. Required if location not provided.
examples:
- 72.8692
timezone:
anyOf:
- type: string
- type: 'null'
title: Timezone
description: IANA timezone. Required if location not provided (unless utc_offset is given). For dates before the zone adopted a standard time, the birthplace's local mean time (longitude / 15 hours) is used.
examples:
- Asia/Kolkata
utc_offset:
anyOf:
- type: string
- type: 'null'
title: Utc Offset
description: Optional explicit UTC offset of the birth time, as ±HH:MM or ±HH:MM:SS (e.g. '+04:51:31' for Bombay mean time). Overrides the offset `timezone` would give. Use it when the birth record states the offset, or for historical local times the IANA database cannot represent.
examples:
- +05:30
ayanamsa:
type: string
enum:
- lahiri
- raman
- kp
- tropical
title: Ayanamsa
description: 'Ignored: KP always uses the Krishnamurti (KP) ayanamsa. Accepted so requests that send it keep working.'
default: lahiri
examples:
- kp
type: object
required:
- date
- time
title: KPBirthRequest
description: 'KP natal chart / significators — extends :class:`TimedBirthInput`.
Fields: ``name``, ``date``, ``time``, ``location`` or ``latitude``/``longitude``/
``timezone``, ``ayanamsa``. KP always uses the Krishnamurti ayanamsa: the
``ayanamsa`` field is accepted (so requests that send it keep working) but
ignored, and the schema says so.'
example:
ayanamsa: lahiri
date: '1985-11-12'
latitude: 19.055
location: Mumbai
longitude: 72.8692
name: Arjun Mehta
time: 06:45
timezone: Asia/Kolkata
KPRulingPlanetsRequest:
properties:
latitude:
type: number
maximum: 90.0
minimum: -90.0
title: Latitude
description: Location latitude in decimal degrees. North positive, south negative.
longitude:
type: number
maximum: 180.0
minimum: -180.0
title: Longitude
description: Location longitude in decimal degrees. East positive, west negative.
target_date:
anyOf:
- type: string
- type: 'null'
title: Target Date
description: 'YYYY-MM-DD, local date in `target_timezone`. Omit together with `target_time` to use the current instant. Given without `target_time`, 12:00 local on that date is used. A date that is not in the calendar (e.g. 2026-02-30) is rejected with 422 saying the date does not exist. Supported dates: 1800-01-01 to 2099-12-31.'
target_time:
anyOf:
- type: string
- type: 'null'
title: Target Time
description: HH:MM (24-hour), local time in `target_timezone`. Given without `target_date`, that time today is used. Omit together with `target_date` to use the current instant. A time skipped by a daylight-saving change (e.g. 02:30 on 2026-03-08 in America/New_York) is read with the offset in force before the change, i.e. moved forward by the gap (03:30 EDT); a time that occurred twice is read as the first occurrence. `local_time_status` in the response says which applied.
target_timezone:
anyOf:
- type: string
- type: 'null'
title: Target Timezone
description: IANA timezone (or explicit UTC offset) for `target_date` and `target_time`. Defaults to the time zone at the coordinates.
type: object
required:
- latitude
- longitude
title: KPRulingPlanetsRequest
KPSignificatorsResponse:
properties:
birth_time_provided:
type: boolean
title: Birth Time Provided
description: 'True when a birth time was supplied. False when it was not: house, Ascendant and Moon-dependent results then carry the accuracy limits of an unknown birth time.'
default: true
ayanamsa:
type: string
title: Ayanamsa
significators:
additionalProperties:
$ref: '#/components/schemas/KPHouseSignificators'
type: object
title: Significators
planet_significators:
additionalProperties:
additionalProperties: true
type: object
type: object
title: Planet Significators
type: object
required:
- ayanamsa
- significators
- planet_significators
title: KPSignificatorsResponse
KPRulingPlanetBody:
properties:
longitude:
type: number
title: Longitude
rashi:
type: string
title: Rashi
sign_lord:
type: string
title: Sign Lord
nakshatra_lord:
type: string
title: Nakshatra Lord
sub_lord:
type: string
title: Sub Lord
type: object
required:
- longitude
- rashi
- sign_lord
- nakshatra_lord
- sub_lord
title: KPRulingPlanetBody
KPChartResponse:
properties:
birth_time_provided:
type: boolean
title: Birth Time Provided
description: 'True when a birth time was supplied. False when it was not: house, Ascendant and Moon-dependent results then carry the accuracy limits of an unknown birth time.'
default: true
ayanamsa:
type: string
title: Ayanamsa
house_basis:
type: string
title: House Basis
description: How planet `house` is assigned. Always 'placidus_cusp_to_cusp' (KP occupancy between consecutive sidereal Placidus cusps).
lagna:
$ref: '#/components/schemas/KPLagna'
planets:
additionalProperties:
$ref: '#/components/schemas/KPPlanet'
type: object
title: Planets
house_cusps:
additionalProperties:
additionalProperties: true
type: object
type: object
title: House Cusps
type: object
required:
- ayanamsa
- house_basis
- lagna
- planets
- house_cusps
title: KPChartResponse
KPLagna:
properties:
rashi:
type: string
title: Rashi
rashi_index:
type: integer
title: Rashi Index
longitude:
type: number
title: Longitude
nakshatra_lord:
type: string
title: Nakshatra Lord
sub_lord:
type: string
title: Sub Lord
type: object
required:
- rashi
- rashi_index
- longitude
- nakshatra_lord
- sub_lord
title: KPLagna
ErrorResponse:
properties:
success:
type: boolean
title: Success
description: Always false for error responses.
default: false
examples:
- false
error:
$ref: '#/components/schemas/ErrorCode'
description: Machine-readable error code. Use this for programmatic error handling. See doc_url for the canonical docs page. The full set of codes is the ErrorCode enum in this schema.
examples:
- validation_error
message:
type: string
title: Message
description: Human-readable explanation of what went wrong and how to fix it. Safe to surface in customer-facing UIs.
examples:
- 'Invalid house_system ''foo''. Valid options: equal, koch, placidus, porphyry, whole_sign.'
details:
items: {}
type: array
title: Details
description: Optional structured details. For validation errors, contains per-field error objects. Empty list when there are no structured details.
examples:
- - loc:
- body
- date
msg: Invalid date
retry_after:
anyOf:
- type: integer
- type: 'null'
title: Retry After
description: Seconds to wait before retrying. Present on 429 (rate limit) and 503 (temporary outage) responses. Null when retry is not advised or applicable.
examples:
- 60
doc_url:
type: string
title: Doc Url
description: Canonical documentation URL for this error code. Contains causes, examples, and resolution steps.
examples:
- https://docs.asterwise.com/reference/errors/validation_error/
request_id:
anyOf:
- type: string
- type: 'null'
title: Request Id
description: Unique identifier for this request. Include when contacting support to enable rapid investigation.
examples:
- 3f2b8c1e-7a4d-4e9b-8c21-5d6f0a9b1e37
timestamp:
anyOf:
- type: string
- type: 'null'
title: Timestamp
description: ISO 8601 timestamp of when the error occurred. UTC.
examples:
- '2026-05-19T12:34:56.789Z'
type: object
required:
- error
- message
- doc_url
title: ErrorResponse
description: 'Standard error envelope returned by all Asterwise API endpoints.
Every error response follows this 8-field shape. The ''error'' field
is the machine-readable identifier (use it for programmatic handling).
The ''message'' field is the human-readable explanation. The ''doc_url''
field links to the canonical documentation for the error code.
Include ''request_id'' when contacting support.'
KPHouseSignificators:
properties:
house:
type: integer
title: House
sign_lord:
type: string
title: Sign Lord
description: Lord of the sign on the cusp (the house owner).
occupants:
items:
type: string
type: array
title: Occupants
description: Planets in the house (cusp to cusp).
nak_of_occupants:
items:
type: string
type: array
title: Nak Of Occupants
description: Planets in the nakshatra (star) of an occupant.
nak_of_lord:
items:
type: string
type: array
title: Nak Of Lord
description: Planets in the nakshatra of the cusp sign lord.
all_significators:
items:
type: string
type: array
title: All Significators
description: 'Union in the original order: occupants, sign lord, star of occupants, star of sign lord. Not a ranking; see `strength_order`.'
strength_order:
items:
type: string
type: array
title: Strength Order
description: 'The same planets ranked strongest first per Krishnamurti: planets in the star of occupants, occupants, planets in the star of the sign lord, the sign lord. Each planet appears once, at its strongest level.'
type: object
required:
- house
- sign_lord
- occupants
- nak_of_occupants
- nak_of_lord
- all_significators
- strength_order
title: KPHouseSignificators
KPRulingPlanetsResponse:
properties:
ayanamsa:
type: string
title: Ayanamsa
target_utc:
type: string
title: Target Utc
description: The instant used, ISO 8601 UTC.
target_timezone:
type: string
title: Target Timezone
description: Time zone used to read `target_date`/`target_time` and for the sunrise-based day lord.
local_time_status:
type: string
enum:
- ok
- nonexistent
- ambiguous
title: Local Time Status
description: 'How `target_date`/`target_time` was read. ''nonexistent'': the local time fell in a daylight-saving gap and was read with the offset in force before the change (moved forward by the gap). ''ambiguous'': the local time occurred twice and the first occurrence was used. ''ok'' otherwise, including when the current instant was used.'
default: ok
day_lord:
type: string
title: Day Lord
moon:
$ref: '#/components/schemas/KPRulingPlanetBody'
ascendant:
$ref: '#/components/schemas/KPRulingPlanetBody'
ruling_planets:
items:
type: string
type: array
title: Ruling Planets
type: object
required:
- ayanamsa
- target_utc
- target_timezone
- day_lord
- moon
- ascendant
- ruling_planets
title: KPRulingPlanetsResponse
ApiResponse_KPChartResponse_:
properties:
success:
type: boolean
title: Success
description: True if the request succeeded
default: true
message:
type: string
title: Message
description: Human-readable status message
default: success
data:
$ref: '#/components/schemas/KPChartResponse'
description: The endpoint response payload
type: object
required:
- data
title: ApiResponse[KPChartResponse]
KPPlanet:
properties:
longitude:
type: number
title: Longitude
description: Sidereal longitude (KP ayanamsa), degrees 0-360.
rashi_index:
type: integer
title: Rashi Index
description: Sign index, 0 = Mesha … 11 = Meena.
rashi:
type: string
title: Rashi
degree:
type: number
title: Degree
description: Degrees within the sign.
is_retrograde:
type: boolean
title: Is Retrograde
description: True when the longitude speed is negative. Rahu and Ketu are the mean node, which is always retrograde.
house:
type: integer
title: House
description: 'KP house (1-12), cusp to cusp: from cusp h up to, not including, cusp h+1 of the sidereal Placidus cusps. A planet exactly on a cusp is in the house that cusp starts.'
rasi_house:
type: integer
title: Rasi House
description: Whole-sign house (1-12) counted from the lagna sign, for comparison with Parashari charts.
nakshatra_index:
type: integer
title: Nakshatra Index
description: Nakshatra index 0-26.
nakshatra_lord:
type: string
title: Nakshatra Lord
description: Star lord (nakshatra lord).
sub_lord:
type: string
title: Sub Lord
description: KP sub-lord.
type: object
required:
- longitude
- rashi_index
- rashi
- degree
- is_retrograde
- house
- rasi_house
- nakshatra_index
- nakshatra_lord
- sub_lord
title: KPPlanet
ApiResponse_KPSignificatorsResponse_:
properties:
success:
type: boolean
title: Success
description: True if the request succeeded
default: true
message:
type: string
title: Message
description: Human-readable status message
default: success
data:
$ref: '#/components/schemas/KPSignificatorsResponse'
description: The endpoint response payload
type: object
required:
- data
title: ApiResponse[KPSignificatorsResponse]
ApiResponse_KPRulingPlanetsResponse_:
properties:
success:
type: boolean
title: Success
description: True if the request succeeded
default: true
message:
type: string
title: Message
description: Human-readable status message
default: success
data:
$ref: '#/components/schemas/KPRulingPlanetsResponse'
description: The endpoint response payload
type: object
required:
- data
title: ApiResponse[KPRulingPlanetsResponse]
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: 'Pass your Asterwise API key as a Bearer token. Example: Authorization: Bearer aw_live_xxxx'