asterwise-com Keys API

openapi: 3.2.0
info:
  title: Asterwise Keys 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: Keys
paths:
  /v1/keys/me/usage:
    get:
      tags:
      - Keys
      summary: Get this month's usage for your account
      description: Returns the calls the key's account has used this UTC month, its monthly limit, its per-minute limit and when the month resets. The limits are shared by every key on the account, so these are the counts the 429 responses are enforced on. This call is not billed and does not use the plan's limits; each key may make it 60 times a minute (together with GET /v1/keys/me). Every billed answer carries the same numbers in its X-RateLimit-* headers.
      operationId: get_my_usage_v1_keys_me_usage_get
      responses:
        '200':
          description: Monthly usage summary for the key's account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_MyUsageResponse_'
        '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-account-endpoint: true
      security:
      - BearerAuth: []
components:
  schemas:
    MyUsageResponse:
      properties:
        calls_used:
          type: integer
          minimum: 0.0
          title: Calls Used
          examples:
          - 142
        calls_limit:
          type: integer
          minimum: 0.0
          title: Calls Limit
          examples:
          - 500
        calls_remaining:
          type: integer
          minimum: 0.0
          title: Calls Remaining
          examples:
          - 358
        percent_used:
          type: number
          minimum: 0.0
          title: Percent Used
          examples:
          - 28.4
        tier:
          type: string
          title: Tier
          examples:
          - sandbox
        burst_limit:
          type: integer
          minimum: 0.0
          title: Burst Limit
          description: Calls a minute the plan allows (counted per account in UTC clock minutes).
          examples:
          - 10
        reset_date:
          type: string
          title: Reset Date
          examples:
          - '2026-04-01'
        period_start:
          type: string
          title: Period Start
          examples:
          - '2026-03-01'
        period_end:
          type: string
          title: Period End
          examples:
          - '2026-03-31'
      type: object
      required:
      - calls_used
      - calls_limit
      - calls_remaining
      - percent_used
      - tier
      - burst_limit
      - reset_date
      - period_start
      - period_end
      title: MyUsageResponse
    ApiResponse_MyUsageResponse_:
      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/MyUsageResponse'
          description: The endpoint response payload
      type: object
      required:
      - data
      title: ApiResponse[MyUsageResponse]
    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.'
    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'