asterwise-com Lal Kitab API

openapi: 3.2.0
info:
  title: Asterwise Lal Kitab 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: Lal Kitab
  description: Lal Kitab annual charts and planetary debt remedies.
paths:
  /v1/astro/lal-kitab/chart:
    post:
      tags:
      - Lal Kitab
      summary: Lal Kitab Chart
      description: 'Computes a Lal Kitab chart following the 1952 Lal Kitab: houses are counted from the Vedic lagna (whole sign) and the lagna house is read as house 1 (Aries). Returns the ascendant and all 9 planets with their Lal Kitab house, pakka ghar, uchcha (exalted) and neecha (debilitated) flags, fixed or doubtful effect and malefic indications, the 12 houses, and the 9 Lal Kitab debts (rin) with their remedies. Ayanamsa: lahiri (default), raman or kp; tropical is rejected because Lal Kitab starts from the sidereal Indian chart. Without a birth time a sunrise chart is used and birth_time_provided is false; houses are then approximate.'
      operationId: get_lal_kitab_chart_v1_astro_lal_kitab_chart_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LalKitabRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_LalKitabChartResponse_'
        '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: Lal Kitab
      security:
      - BearerAuth: []
  /v1/astro/lal-kitab/remedies:
    post:
      tags:
      - Lal Kitab
      summary: Lal Kitab Remedies
      description: Lal Kitab remedies for the planets that need them. Following the 1952 Lal Kitab, a planet is listed when its effect is doubtful (it is not in its own house, pakka ghar, or exaltation or debilitation house, or it is a companion planet) and its placement is generally malefic (an enemy's house, or its debilitation house when it is a companion planet). Planets that are malefic but have a fixed effect are listed separately as not remediable. Also returns remedies for any indicated debts (rin).
      operationId: get_lal_kitab_remedies_v1_astro_lal_kitab_remedies_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LalKitabRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_LalKitabRemediesResponse_'
        '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: Lal Kitab
      security:
      - BearerAuth: []
components:
  schemas:
    LalKitabAscendant:
      properties:
        longitude:
          type: number
          title: Longitude
          description: Sidereal ascendant longitude in degrees, in the requested ayanamsa.
        rashi_index:
          type: integer
          title: Rashi Index
          description: Ascendant sign, 0 = Aries. This house is Lal Kitab house 1.
        rashi:
          type: string
          title: Rashi
      type: object
      required:
      - longitude
      - rashi_index
      - rashi
      title: LalKitabAscendant
    LalKitabRemedyItem:
      properties:
        type:
          type: string
          enum:
          - donation
          - keep
          - avoid
          - remedy
          title: Type
          description: donation = give something away or feed; keep = keep or wear an item; avoid = a prohibition; remedy = any other prescribed act.
        action:
          type: string
          title: Action
          description: The remedy, in short.
        page:
          anyOf:
          - type: integer
          - type: 'null'
          title: Page
          description: 'Deprecated: no longer sent.'
          deprecated: true
        condition:
          anyOf:
          - type: string
          - type: 'null'
          title: Condition
          description: Extra condition the book attaches to this remedy; null when it applies whenever the placement is malefic.
        note:
          anyOf:
          - type: string
          - type: 'null'
          title: Note
          description: Set when the book points to another placement's remedy (e.g. 'same as house 4'); says which.
      type: object
      required:
      - type
      - action
      title: LalKitabRemedyItem
    LalKitabChartResponse:
      properties:
        system:
          type: string
          title: System
        ayanamsa:
          type: string
          title: Ayanamsa
        birth_time_provided:
          type: boolean
          title: Birth Time Provided
          description: 'False when no birth time was given: a sunrise chart is used, so the lagna and every house are approximate.'
          default: true
        ascendant:
          $ref: '#/components/schemas/LalKitabAscendant'
        planets:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Planets
        houses:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Houses
        rin_analysis:
          additionalProperties: true
          type: object
          title: Rin Analysis
        sources:
          items:
            type: string
          type: array
          title: Sources
      type: object
      required:
      - system
      - ayanamsa
      - ascendant
      - planets
      - houses
      - rin_analysis
      - sources
      title: LalKitabChartResponse
    LalKitabNotRemediable:
      properties:
        planet:
          type: string
          title: Planet
        lk_house:
          type: integer
          title: Lk House
        reasons:
          items:
            type: string
          type: array
          title: Reasons
          description: Why this placement is generally malefic.
      type: object
      required:
      - planet
      - lk_house
      - reasons
      title: LalKitabNotRemediable
    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.'
    LalKitabRinFound:
      properties:
        planet:
          type: string
          title: Planet
        house:
          type: integer
          title: House
      type: object
      required:
      - planet
      - house
      title: LalKitabRinFound
    LalKitabRemediesResponse:
      properties:
        system:
          type: string
          title: System
        ayanamsa:
          type: string
          title: Ayanamsa
        birth_time_provided:
          type: boolean
          title: Birth Time Provided
          description: 'False when no birth time was given: a sunrise chart is used, so the lagna and every house are approximate.'
          default: true
        ascendant:
          $ref: '#/components/schemas/LalKitabAscendant'
        remedies:
          items:
            $ref: '#/components/schemas/LalKitabPlanetRemedy'
          type: array
          title: Remedies
          description: Planets with a doubtful effect and a malefic indication, in the order Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu.
        not_remediable:
          items:
            $ref: '#/components/schemas/LalKitabNotRemediable'
          type: array
          title: Not Remediable
          description: Planets with a malefic indication but a fixed (grah phal) effect, which Lal Kitab says remedies cannot change.
        rin_remedies:
          items:
            $ref: '#/components/schemas/LalKitabRinRemedy'
          type: array
          title: Rin Remedies
        rule:
          type: string
          title: Rule
        sources:
          items:
            type: string
          type: array
          title: Sources
      type: object
      required:
      - system
      - ayanamsa
      - ascendant
      - remedies
      - not_remediable
      - rin_remedies
      - rule
      - sources
      title: LalKitabRemediesResponse
    LalKitabRinRemedy:
      properties:
        rin:
          type: string
          title: Rin
        name:
          type: string
          title: Name
        planet:
          type: string
          title: Planet
          description: The planet the debt belongs to.
        houses:
          items:
            type: integer
          type: array
          title: Houses
          description: That planet's houses where an enemy indicates the debt.
        found:
          items:
            $ref: '#/components/schemas/LalKitabRinFound'
          type: array
          title: Found
          description: Enemy planets found in those houses.
        remedy:
          type: string
          title: Remedy
        source:
          type: string
          title: Source
      type: object
      required:
      - rin
      - name
      - planet
      - houses
      - found
      - remedy
      - source
      title: LalKitabRinRemedy
    ApiResponse_LalKitabRemediesResponse_:
      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/LalKitabRemediesResponse'
          description: The endpoint response payload
      type: object
      required:
      - data
      title: ApiResponse[LalKitabRemediesResponse]
    LalKitabRequest:
      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:
          anyOf:
          - type: string
          - type: 'null'
          title: Time
          description: Birth time in HH:MM 24-hour format. If omitted, sunrise chart is used as 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
          title: Ayanamsa
          description: 'Sidereal ayanamsa used to cast the birth chart: lahiri (default), raman or kp. Tropical is rejected: Lal Kitab starts from the sidereal Indian chart.'
          default: lahiri
          examples:
          - lahiri
      type: object
      required:
      - date
      title: LalKitabRequest
      description: 'Lal Kitab starts from the traditional Indian (sidereal) birth chart and

        names no ayanamsa, so any sidereal ayanamsa is honoured; tropical is not

        the chart the book starts from and is rejected.'
      example:
        ayanamsa: lahiri
        date: '1985-11-12'
        latitude: 19.055
        location: Mumbai
        longitude: 72.8692
        name: Arjun Mehta
        time: 06:45
        timezone: Asia/Kolkata
    LalKitabPlanetRemedy:
      properties:
        planet:
          type: string
          title: Planet
        lk_house:
          type: integer
          title: Lk House
        rashi:
          type: string
          title: Rashi
        pucca_ghar:
          type: boolean
          title: Pucca Ghar
        uchcha:
          type: boolean
          title: Uchcha
        neecha:
          type: boolean
          title: Neecha
        effect:
          type: string
          const: doubtful
          title: Effect
          description: 'Always ''doubtful'' here: only planets with a doubtful (rashi phal) effect can be remedied.'
        malefic_reasons:
          items:
            type: string
          type: array
          title: Malefic Reasons
          description: Why this placement is generally malefic.
        remedies:
          items:
            $ref: '#/components/schemas/LalKitabRemedyItem'
          type: array
          title: Remedies
          description: Remedies the book gives for this planet in this house; empty when it gives none.
      type: object
      required:
      - planet
      - lk_house
      - rashi
      - pucca_ghar
      - uchcha
      - neecha
      - effect
      - malefic_reasons
      - remedies
      title: LalKitabPlanetRemedy
    ApiResponse_LalKitabChartResponse_:
      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/LalKitabChartResponse'
          description: The endpoint response payload
      type: object
      required:
      - data
      title: ApiResponse[LalKitabChartResponse]
    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
  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'