asterwise-com Prashna API

openapi: 3.2.0
info:
  title: Asterwise Prashna 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: Prashna
  description: Prashna (horary) astrology — chart cast for the moment of a question.
paths:
  /v1/astro/prashna:
    post:
      tags:
      - Prashna
      summary: Prashna (Horary Chart)
      description: Computes a Prashna (Horary) chart for the exact moment a question is asked. Returns lagna, Moon analysis, house lord condition, occupants of the relevant house, and a classical verdict (favourable / unfavourable / mixed) with confidence level. Question category determines which house is analysed; that house and its lord are taken by whole sign from the lagna, like the planets' houses.
      operationId: get_prashna_v1_astro_prashna_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrashnaRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_PrashnaResponse_'
        '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: Forecasting
      security:
      - BearerAuth: []
components:
  schemas:
    PrashnaVerdict:
      properties:
        verdict:
          type: string
          title: Verdict
        confidence:
          type: string
          title: Confidence
        score:
          type: integer
          title: Score
      type: object
      required:
      - verdict
      - confidence
      - score
      title: PrashnaVerdict
    PrashnaLagna:
      properties:
        rashi_index:
          type: integer
          title: Rashi Index
        rashi:
          type: string
          title: Rashi
        longitude:
          type: number
          title: Longitude
        lord:
          type: string
          title: Lord
      type: object
      required:
      - rashi_index
      - rashi
      - longitude
      - lord
      title: PrashnaLagna
    PrashnaHouseAnalysis:
      properties:
        house:
          type: integer
          title: House
        rashi_index:
          type: integer
          title: Rashi Index
          description: Sign of the quesited house, counted whole sign from the lagna sign (0 = Mesha).
        rashi:
          type: string
          title: Rashi
        lord:
          type: string
          title: Lord
          description: Lord of the quesited house by whole sign (lord of its sign), as BPHS reads lordship.
        lord_dignity:
          type: string
          title: Lord Dignity
        lord_house:
          type: integer
          title: Lord House
        lord_longitude:
          type: number
          title: Lord Longitude
        occupants:
          items:
            type: string
          type: array
          title: Occupants
      type: object
      required:
      - house
      - rashi_index
      - rashi
      - lord
      - lord_dignity
      - lord_house
      - lord_longitude
      - occupants
      title: PrashnaHouseAnalysis
    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.'
    PrashnaMoon:
      properties:
        longitude:
          type: number
          title: Longitude
        rashi_index:
          type: integer
          title: Rashi Index
        rashi:
          type: string
          title: Rashi
        nakshatra:
          type: string
          title: Nakshatra
        phase:
          type: string
          title: Phase
        dignity:
          type: string
          title: Dignity
        void_of_course:
          type: boolean
          title: Void Of Course
        afflicted_moon:
          type: boolean
          title: Afflicted Moon
        applying_to_benefic:
          type: boolean
          title: Applying To Benefic
      type: object
      required:
      - longitude
      - rashi_index
      - rashi
      - nakshatra
      - phase
      - dignity
      - void_of_course
      - afflicted_moon
      - applying_to_benefic
      title: PrashnaMoon
    PrashnaPlanetSummary:
      properties:
        longitude:
          type: number
          title: Longitude
        rashi_index:
          type: integer
          title: Rashi Index
        rashi:
          type: string
          title: Rashi
        house:
          type: integer
          title: House
        is_retrograde:
          type: boolean
          title: Is Retrograde
        dignity:
          type: string
          title: Dignity
      type: object
      required:
      - longitude
      - rashi_index
      - rashi
      - house
      - is_retrograde
      - dignity
      title: PrashnaPlanetSummary
    ApiResponse_PrashnaResponse_:
      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/PrashnaResponse'
          description: The endpoint response payload
      type: object
      required:
      - data
      title: ApiResponse[PrashnaResponse]
    PrashnaResponse:
      properties:
        ayanamsa:
          type: string
          title: Ayanamsa
        question:
          type: string
          title: Question
        primary_house:
          type: integer
          title: Primary House
        ithsala_applying:
          type: boolean
          title: Ithsala Applying
          description: 'Tajika Ithasala (applying) between the Lagna lord and the quesited house lord, by the Varshaphal rule: Tajika aspect by sign (same sign, 3rd/11th, 4th/10th, 5th/9th, 7th), the faster planet by mean motion (Moon, Mercury, Venus, Sun, Mars, Jupiter, Saturn) behind the slower in degrees within the mean of their Deeptamsas. Retrogression is not modelled. False when one planet rules both houses (always for ''self''; compare lagna.lord and house_analysis.lord).'
        ithsala_separating:
          type: boolean
          title: Ithsala Separating
          description: 'Tajika Musaripha (separating): the two lords in Tajika aspect within the same orb but the faster planet already past the slower one''s degree. False when one planet rules both houses.'
        query_utc:
          type: string
          title: Query Utc
        lagna:
          $ref: '#/components/schemas/PrashnaLagna'
        house_analysis:
          $ref: '#/components/schemas/PrashnaHouseAnalysis'
        moon:
          $ref: '#/components/schemas/PrashnaMoon'
        verdict:
          $ref: '#/components/schemas/PrashnaVerdict'
        planets:
          additionalProperties:
            $ref: '#/components/schemas/PrashnaPlanetSummary'
          type: object
          title: Planets
        house_cusps:
          additionalProperties:
            $ref: '#/components/schemas/PrashnaHouseCusp'
          type: object
          title: House Cusps
      type: object
      required:
      - ayanamsa
      - question
      - primary_house
      - ithsala_applying
      - ithsala_separating
      - query_utc
      - lagna
      - house_analysis
      - moon
      - verdict
      - planets
      - house_cusps
      title: PrashnaResponse
    PrashnaHouseCusp:
      properties:
        rashi_index:
          type: integer
          title: Rashi Index
        rashi:
          type: string
          title: Rashi
        lord:
          type: string
          title: Lord
          description: Lord of the sign on this quadrant cusp. House lordship in house_analysis is whole sign and can differ.
        longitude:
          type: number
          title: Longitude
      type: object
      required:
      - rashi_index
      - rashi
      - lord
      - longitude
      title: PrashnaHouseCusp
    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
    PrashnaRequest:
      properties:
        latitude:
          type: number
          maximum: 90.0
          minimum: -90.0
          title: Latitude
          description: Querent location latitude
        longitude:
          type: number
          maximum: 180.0
          minimum: -180.0
          title: Longitude
          description: Querent location longitude
        question:
          type: string
          enum:
          - self
          - wealth
          - siblings
          - property
          - children
          - health
          - marriage
          - death
          - travel
          - career
          - gains
          - loss
          title: Question
          description: Question category
        target_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Target Date
          description: 'YYYY-MM-DD. Defaults to now: the current date and time in target_timezone.'
        target_time:
          anyOf:
          - type: string
          - type: 'null'
          title: Target Time
          description: HH:MM (24h), with target_date. Defaults to the current time in target_timezone; ignored without target_date.
        target_timezone:
          anyOf:
          - type: string
          - type: 'null'
          title: Target Timezone
          description: IANA timezone for input date/time
          default: Asia/Kolkata
        ayanamsa:
          type: string
          enum:
          - lahiri
          - raman
          - kp
          - tropical
          title: Ayanamsa
          description: 'Ayanamsa system: lahiri (default), raman, kp, or tropical for a zero offset, as on every other chart endpoint'
          default: lahiri
      type: object
      required:
      - latitude
      - longitude
      - question
      title: PrashnaRequest
  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'