AsterNym Bazi API

openapi: 3.2.0
info:
  title: AsterNym reading Bazi 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: Bazi
paths:
  /api/v1/bazi:
    get:
      operationId: getBazi
      summary: The BaZi Four Pillars alone, with hidden stems and ten gods.
      description: Pillars, day master, hidden stems (藏干) with their ten gods (十神), element counts, dominant and missing elements, na yin, the twelve stages and the void branches. The year turns at Li Chun, not at 1 January or Lunar New Year. Without a time there is no hour pillar and the response says so.
      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: sexCategory
        in: query
        required: false
        schema:
          type: string
          enum:
          - F
          - M
          - both
        description: Echoed back. Only the luck-pillar cycle reads it, and this endpoint does not return luck pillars.
      - 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: The BaZi Four Pillars alone, with hidden stems and ten gods.
          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:
      - Bazi
    post:
      operationId: postBazi
      summary: The BaZi Four Pillars alone, with hidden stems and ten gods.
      description: Pillars, day master, hidden stems (藏干) with their ten gods (十神), element counts, dominant and missing elements, na yin, the twelve stages and the void branches. The year turns at Li Chun, not at 1 January or Lunar New Year. Without a time there is no hour pillar and the response says so.
      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.
                sexCategory:
                  type: string
                  enum:
                  - F
                  - M
                  - both
                  description: Echoed back. Only the luck-pillar cycle reads it, and this endpoint does not return luck pillars.
                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: The BaZi Four Pillars alone, with hidden stems and ten gods.
          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:
      - Bazi
  /api/v1/bazi/hours:
    get:
      operationId: getBaziHours
      summary: Every BaZi double-hour of one civil date, optionally ranked by element.
      description: 'The twelve 時辰 of a day, each with its hour pillar, hidden stems, ten god and the element counts of the whole chart at that hour. The 23:00-00:00 slot is returned separately as lateZi: from 23:00 the hour pillar has already turned to the next day''s 子 (早子時) while the day pillar has not, so it differs from the 00:00-01:00 slot on the same date. These are the Chinese double-hours, not the Western planetary hours.'
      parameters:
      - name: date
        in: query
        required: true
        schema:
          type: string
          format: date
        description: Local civil date, YYYY-MM-DD. Required.
      - 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: element
        in: query
        required: false
        schema:
          type: string
          enum:
          - Wood
          - Fire
          - Earth
          - Metal
          - Water
        description: 'Optional: rank the hours by how much of this element the chart carries.'
      - 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: Every BaZi double-hour of one civil date, optionally ranked by element.
          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:
      - Bazi
    post:
      operationId: postBaziHours
      summary: Every BaZi double-hour of one civil date, optionally ranked by element.
      description: 'The twelve 時辰 of a day, each with its hour pillar, hidden stems, ten god and the element counts of the whole chart at that hour. The 23:00-00:00 slot is returned separately as lateZi: from 23:00 the hour pillar has already turned to the next day''s 子 (早子時) while the day pillar has not, so it differs from the 00:00-01:00 slot on the same date. These are the Chinese double-hours, not the Western planetary hours.'
      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.
                tz:
                  type: string
                  description: IANA time zone, e.g. Asia/Singapore. Required when lat and lng are given.
                element:
                  type: string
                  enum:
                  - Wood
                  - Fire
                  - Earth
                  - Metal
                  - Water
                  description: 'Optional: rank the hours by how much of this element the chart carries.'
                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: Every BaZi double-hour of one civil date, optionally ranked by element.
          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:
      - Bazi
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