AsterNym Natal API

openapi: 3.2.0
info:
  title: AsterNym reading Natal 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: Natal
paths:
  /api/v1/natal:
    get:
      operationId: getNatal
      summary: 'The Western natal chart: planets, houses, angles, nodes and aspects.'
      description: 'Ten planets with sign, degree, whole-sign house and retrograde flag; the Ascendant, midheaven and their opposites; the twelve whole-sign houses; the mean lunar nodes; the five major aspects with orb and whether each is applying or separating; plus stelliums, retrogrades and the Moon''s phase. Tropical zodiac, geocentric apparent positions, astronomy-engine. This is the one endpoint that requires lat, lng and tz: the angles and houses are a place on the Earth meeting the sky. A time is optional, and without one the angles and houses are null rather than taken from noon, and the Moon is a noon estimate the notes warn about.'
      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: true
        schema:
          type: string
        description: IANA time zone, e.g. Asia/Singapore. Required when lat and lng are given.
      - name: lat
        in: query
        required: true
        schema:
          type: number
          minimum: -90
          maximum: 90
        description: Decimal degrees.
      - name: lng
        in: query
        required: true
        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: 'The Western natal chart: planets, houses, angles, nodes and aspects.'
          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:
      - Natal
    post:
      operationId: postNatal
      summary: 'The Western natal chart: planets, houses, angles, nodes and aspects.'
      description: 'Ten planets with sign, degree, whole-sign house and retrograde flag; the Ascendant, midheaven and their opposites; the twelve whole-sign houses; the mean lunar nodes; the five major aspects with orb and whether each is applying or separating; plus stelliums, retrogrades and the Moon''s phase. Tropical zodiac, geocentric apparent positions, astronomy-engine. This is the one endpoint that requires lat, lng and tz: the angles and houses are a place on the Earth meeting the sky. A time is optional, and without one the angles and houses are null rather than taken from noon, and the Moon is a noon estimate the notes warn about.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - date
              - lat
              - lng
              - tz
              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: 'The Western natal chart: planets, houses, angles, nodes and aspects.'
          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:
      - Natal
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