asterwise-com Dreams API

openapi: 3.2.0
info:
  title: Asterwise Dreams 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: Dreams
paths:
  /v1/dreams/symbols:
    get:
      tags:
      - Dreams
      summary: Dream symbol database
      description: 'Returns all dream symbols from the database, optionally filtered by category. Each symbol includes dual-tradition interpretation: Jungian/Western psychological analysis and classical Vedic dream tradition meaning with auspiciousness rating. The traditions_agree field flags where Western and Vedic interpretations conflict. Categories: animals, nature, people, places, objects, actions, body, abstract.'
      operationId: get_symbols_v1_dreams_symbols_get
      parameters:
      - name: category
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by category: animals, nature, people, places, objects, actions, body, abstract.'
          examples:
          - animals
          title: Category
        description: 'Filter by category: animals, nature, people, places, objects, actions, body, abstract.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_DreamSymbolListResponse_'
        '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'
      security:
      - BearerAuth: []
  /v1/dreams/symbol/{name}:
    get:
      tags:
      - Dreams
      summary: Single dream symbol lookup
      description: 'Lookup a specific dream symbol by slug or name (case-insensitive). Examples: ''snake'', ''eagle'', ''childhood-home'', ''teeth falling out''. Returns full dual-tradition interpretation including Jungian archetype, Vedic dream tradition meaning, context variants, and related symbols.'
      operationId: get_symbol_v1_dreams_symbol__name__get
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          title: Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_DreamSymbol_'
        '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'
      security:
      - BearerAuth: []
components:
  schemas:
    ApiResponse_DreamSymbolListResponse_:
      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/DreamSymbolListResponse'
          description: The endpoint response payload
      type: object
      required:
      - data
      title: ApiResponse[DreamSymbolListResponse]
    DreamSymbol:
      properties:
        slug:
          type: string
          title: Slug
          description: URL-safe identifier.
        name:
          type: string
          title: Name
          description: Display name of the symbol.
        category:
          type: string
          title: Category
          description: 'Symbol category: animals, nature, people, places, objects, actions, body, or abstract.'
        jungian_meaning:
          type: string
          title: Jungian Meaning
          description: Jungian/Western psychological interpretation.
        jungian_archetype:
          type: string
          title: Jungian Archetype
          description: Primary Jungian archetype activated by this symbol.
        vedic_meaning:
          type: string
          title: Vedic Meaning
          description: Classical Vedic dream tradition interpretation.
        vedic_auspicious:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Vedic Auspicious
          description: True if auspicious (Shubha), False if inauspicious (Ashubha), null if mixed/context-dependent.
        traditions_agree:
          type: string
          title: Traditions Agree
          description: 'Whether Jungian and Vedic traditions agree: ''agree'', ''conflict'', or ''partial''.'
        emotional_tone:
          type: string
          title: Emotional Tone
          description: 'Primary emotional register: anxiety, transformation, auspicious, warning, grief, power, healing, clarity, confusion, or neutral.'
        themes:
          items:
            type: string
          type: array
          title: Themes
          description: Thematic keywords used for AI synthesis and search.
        context_variants:
          items:
            $ref: '#/components/schemas/ContextVariant'
          type: array
          title: Context Variants
          description: Alternative readings depending on dream context.
        related_symbols:
          items:
            type: string
          type: array
          title: Related Symbols
          description: 'Slugs of four related dream symbols: hand-picked links first, then the most similar symbols by category, themes and meaning. Every slug exists in the catalogue; links are reciprocal.'
      type: object
      required:
      - slug
      - name
      - category
      - jungian_meaning
      - jungian_archetype
      - vedic_meaning
      - traditions_agree
      - emotional_tone
      - themes
      - context_variants
      - related_symbols
      title: DreamSymbol
    ContextVariant:
      properties:
        context:
          type: string
          title: Context
          description: The specific dream context or variant.
        meaning:
          type: string
          title: Meaning
          description: The interpretation for this specific context.
      type: object
      required:
      - context
      - meaning
      title: ContextVariant
    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.'
    DreamSymbolListResponse:
      properties:
        total:
          type: integer
          title: Total
          description: Total number of symbols returned.
        category_filter:
          anyOf:
          - type: string
          - type: 'null'
          title: Category Filter
          description: Category filter applied, if any.
        symbols:
          items:
            $ref: '#/components/schemas/DreamSymbol'
          type: array
          title: Symbols
          description: Dream symbols sorted alphabetically.
      type: object
      required:
      - total
      - symbols
      title: DreamSymbolListResponse
    ApiResponse_DreamSymbol_:
      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/DreamSymbol'
          description: The endpoint response payload
      type: object
      required:
      - data
      title: ApiResponse[DreamSymbol]
    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'