asterwise-com Vedic Reference API

openapi: 3.2.0
info:
  title: Asterwise Vedic Reference 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: Vedic Reference
paths:
  /v1/astro/reference-charts:
    get:
      tags:
      - Vedic Reference
      summary: Published reference charts
      description: Test charts with reference values from an independent source, so anyone can check the maths. The 25 edge cases of the verification harness (clock changes, southern hemisphere, polar night and day, the date line, 45-minute zones, historical offsets, leap day, the range limits) and a sample of random charts, each with the sidereal longitudes, signs, nakshatras and ascendant from an independent reference implementation, plus a Moon-on-a-nakshatra-boundary case from a direct Swiss Ephemeris call and an unknown-birth-time behaviour case. Send each input to /v1/astro/natal and compare.
      operationId: get_reference_charts_v1_astro_reference_charts_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_ReferenceChartsResponse_'
        '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: Reference
      security:
      - BearerAuth: []
  /v1/astro/significations:
    get:
      tags:
      - Vedic Reference
      summary: Vedic significations (BPHS)
      description: 'What each house and planet signifies in Brihat Parashara Hora Shastra, as a fixed list with stable ids. Houses: chapter 11, verses 2-13. Planets: chapter 3, verses 12-13 and the karaka verses of chapters 8 and 14 (Santhanam edition). Rahu and Ketu are left out because BPHS gives them no such verse. Two levels: a domain (relationships, work, wealth …) and the signification itself. Ids are stable: never renamed, removed or reused; a retired entry stays with deprecated=true and replaced_by. The list says what the texts say; it does not decide what counts as love, work or energy for an app, so each app keeps its own mapping. Cacheable for a day.'
      operationId: get_vedic_significations_v1_astro_significations_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_SignificationsResponse_'
        '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: Reference
      security:
      - BearerAuth: []
components:
  schemas:
    ApiResponse_ReferenceChartsResponse_:
      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/ReferenceChartsResponse'
          description: The endpoint response payload
      type: object
      required:
      - data
      title: ApiResponse[ReferenceChartsResponse]
    HouseSignifications:
      properties:
        house:
          type: integer
          maximum: 12.0
          minimum: 1.0
          title: House
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        label:
          type: string
          title: Label
        source:
          type: string
          title: Source
        significations:
          items:
            $ref: '#/components/schemas/Signification'
          type: array
          title: Significations
      type: object
      required:
      - house
      - id
      - name
      - label
      - source
      - significations
      title: HouseSignifications
    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.'
    ReferenceChart:
      properties:
        id:
          type: string
          title: Id
        covers:
          type: string
          title: Covers
          description: The hard case this chart exercises.
        input:
          additionalProperties: true
          type: object
          title: Input
          description: The exact request body for /v1/astro/natal (time null = unknown birth time).
        expected:
          additionalProperties: true
          type: object
          title: Expected
          description: 'Reference values: UTC instant, local time status, true ayanamsa, planets (sidereal longitude, sign, nakshatra, pada, retrograde) and ascendant.'
        reference_source:
          type: string
          title: Reference Source
          description: Where the expected values come from. Never Asterwise.
        tolerance:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Tolerance
          description: How close a correct engine must come.
      type: object
      required:
      - id
      - covers
      - input
      - expected
      - reference_source
      title: ReferenceChart
    Signification:
      properties:
        id:
          type: string
          title: Id
          description: Stable id, e.g. bphs.house.7.spouse. Never renamed or reused.
        label:
          type: string
          title: Label
          description: Plain-English label, close to the source wording.
        domain:
          type: string
          title: Domain
          description: Domain id from the domains list.
        source:
          type: string
          title: Source
          description: Verse or page the entry comes from.
        deprecated:
          type: boolean
          title: Deprecated
          description: True when retired; the id stays so old mappings do not break.
          default: false
        replaced_by:
          anyOf:
          - type: string
          - type: 'null'
          title: Replaced By
          description: Id of the entry that replaces a deprecated one.
      type: object
      required:
      - id
      - label
      - domain
      - source
      title: Signification
    SignificationsResponse:
      properties:
        tradition:
          type: string
          enum:
          - vedic
          - western
          title: Tradition
        version:
          type: integer
          title: Version
          description: List version; goes up when entries are added or retired.
        source:
          type: string
          title: Source
        id_policy:
          type: string
          title: Id Policy
        notes:
          items:
            type: string
          type: array
          title: Notes
        domains:
          items:
            $ref: '#/components/schemas/SignificationDomain'
          type: array
          title: Domains
          description: 'The first level: broad areas of life shared by both lists.'
        houses:
          items:
            $ref: '#/components/schemas/HouseSignifications'
          type: array
          title: Houses
        planets:
          items:
            $ref: '#/components/schemas/PlanetSignifications'
          type: array
          title: Planets
      type: object
      required:
      - tradition
      - version
      - source
      - id_policy
      - notes
      - domains
      - houses
      - planets
      title: SignificationsResponse
    PlanetSignifications:
      properties:
        planet:
          type: string
          title: Planet
        id:
          type: string
          title: Id
        significations:
          items:
            $ref: '#/components/schemas/Signification'
          type: array
          title: Significations
      type: object
      required:
      - planet
      - id
      - significations
      title: PlanetSignifications
    ReferenceChartsResponse:
      properties:
        version:
          type: integer
          title: Version
        how_to_use:
          type: string
          title: How To Use
        harness:
          type: string
          title: Harness
        charts:
          items:
            $ref: '#/components/schemas/ReferenceChart'
          type: array
          title: Charts
      type: object
      required:
      - version
      - how_to_use
      - harness
      - charts
      title: ReferenceChartsResponse
    ApiResponse_SignificationsResponse_:
      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/SignificationsResponse'
          description: The endpoint response payload
      type: object
      required:
      - data
      title: ApiResponse[SignificationsResponse]
    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
    SignificationDomain:
      properties:
        id:
          type: string
          title: Id
          description: Domain id, e.g. relationships.
        label:
          type: string
          title: Label
      type: object
      required:
      - id
      - label
      title: SignificationDomain
  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'