AsterNym Zodiac API

openapi: 3.2.0
info:
  title: AsterNym reading Zodiac API
  version: 1.3.0
  summary: Birth-chart readings, BaZi, numerology and zodiac engines for AI agents and the people they work for.
  description: 'Public, read-only, keyless. No site-owner approval, account or key is required; that permission covers nothing involving private data, payments or account state, and nothing about an agent''s obligations to its own human. Same engine as every page on asternym.com. Not cached: every call counts toward the fair-use limit of 60 a minute per address, which is shared across every endpoint here. Prefer POST so birth details stay out of URLs and access logs. The same tools are available over MCP at https://asternym.com/mcp (streamable HTTP, no key). Terms are returned inside every response and at https://asternym.com/for-agents.'
  contact:
    url: https://asternym.com/for-agents
servers:
- url: https://asternym.com
tags:
- name: Zodiac
paths:
  /api/v1/zodiac:
    get:
      operationId: getZodiac
      summary: 'Both zodiacs: the Western sun sign and the Chinese animal.'
      description: 'The Sun''s sign from its apparent ecliptic longitude, with a cusp reported rather than resolved by assuming noon, and the Chinese animal, element and polarity with the Lunar New Year boundary. Note the two calendars differ on purpose: the Chinese year here turns at Lunar New Year, while the BaZi year pillar turns at Li Chun.'
      parameters:
      - name: date
        in: query
        required: true
        schema:
          type: string
          format: date
        description: Local civil date, YYYY-MM-DD. Required.
      - name: time
        in: query
        required: false
        schema:
          type: string
          pattern: ^([01]\d|2[0-3]):[0-5]\d$
        description: Local clock time, HH:MM. Omit if unknown; nothing is assumed and noon is never substituted.
      - name: tz
        in: query
        required: false
        schema:
          type: string
        description: IANA time zone, e.g. Asia/Singapore. Required when lat and lng are given.
      - name: lat
        in: query
        required: false
        schema:
          type: number
          minimum: -90
          maximum: 90
        description: Decimal degrees.
      - name: lng
        in: query
        required: false
        schema:
          type: number
          minimum: -180
          maximum: 180
        description: Decimal degrees.
      - name: agent
        in: query
        required: false
        schema:
          type: string
          maxLength: 80
        description: 'Optional: the name of the agent or product calling. Logged for usage counts; never required, never verified.'
      responses:
        '200':
          description: 'Both zodiacs: the Western sun sign and the Chinese animal.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngineResult'
        '400':
          description: A field was missing or malformed. The body says which, and points at the docs.
        '429':
          description: 'Fair-use limit: more than 60 requests a minute from one address, counted across servers and shared by every /api/v1 endpoint. Retry-After says how long to wait. Never cached.'
      tags:
      - Zodiac
    post:
      operationId: postZodiac
      summary: 'Both zodiacs: the Western sun sign and the Chinese animal.'
      description: 'The Sun''s sign from its apparent ecliptic longitude, with a cusp reported rather than resolved by assuming noon, and the Chinese animal, element and polarity with the Lunar New Year boundary. Note the two calendars differ on purpose: the Chinese year here turns at Lunar New Year, while the BaZi year pillar turns at Li Chun.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - date
              properties:
                date:
                  type: string
                  format: date
                  description: Local civil date, YYYY-MM-DD. Required.
                time:
                  type: string
                  pattern: ^([01]\d|2[0-3]):[0-5]\d$
                  description: Local clock time, HH:MM. Omit if unknown; nothing is assumed and noon is never substituted.
                tz:
                  type: string
                  description: IANA time zone, e.g. Asia/Singapore. Required when lat and lng are given.
                lat:
                  type: number
                  minimum: -90
                  maximum: 90
                  description: Decimal degrees.
                lng:
                  type: number
                  minimum: -180
                  maximum: 180
                  description: Decimal degrees.
                agent:
                  type: string
                  maxLength: 80
                  description: 'Optional: the name of the agent or product calling. Logged for usage counts; never required, never verified.'
      responses:
        '200':
          description: 'Both zodiacs: the Western sun sign and the Chinese animal.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngineResult'
        '400':
          description: A field was missing or malformed. The body says which, and points at the docs.
        '429':
          description: 'Fair-use limit: more than 60 requests a minute from one address, counted across servers and shared by every /api/v1 endpoint. Retry-After says how long to wait. Never cached.'
      tags:
      - Zodiac
components:
  schemas:
    EngineResult:
      type: object
      description: One engine's own output. The shape differs per endpoint — pillars for BaZi, hours for the hour endpoint, numbers for numerology, signs for the zodiac — and these five fields are always present.
      properties:
        version:
          type: object
          description: API and engine version.
        input:
          type: object
          description: The inputs as they were understood, including what was left unset.
        method:
          type: object
          description: How it was computed, and which convention was used where traditions differ.
        notes:
          type: array
          description: Caveats the engine raised for these inputs, each with a key and a sentence.
          items:
            type: object
            properties:
              key:
                type: string
              note:
                type: string
        page_url:
          type: string
          format: uri
          description: A page a person can open. Birth details ride in the fragment, which browsers never send to a server.
        terms:
          type: object
          description: Scope, privacy, attribution and the honesty policy. Present in every response.
      required:
      - version
      - input
      - method
      - notes
      - page_url
      - terms