AsterNym Numerology API

openapi: 3.2.0
info:
  title: AsterNym reading Numerology 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: Numerology
paths:
  /api/v1/numerology:
    get:
      operationId: getNumerology
      summary: Life Path and birthday number, plus the name numbers when a name is sent.
      description: 'Pythagorean numerology: Life Path, birthday number and its components, and with a name the expression, soul urge, personality, cornerstone, capstone and hidden passion. Master numbers are kept where the position allows.'
      parameters:
      - name: date
        in: query
        required: true
        schema:
          type: string
          format: date
        description: Local civil date, YYYY-MM-DD. Required.
      - name: name
        in: query
        required: false
        schema:
          type: string
          maxLength: 120
        description: Optional given name. Without it the name numbers are omitted rather than guessed. Used and discarded; never stored.
      - name: surname
        in: query
        required: false
        schema:
          type: string
          maxLength: 120
        description: Optional surname, used with the given name where the method uses the full name.
      - 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: Life Path and birthday number, plus the name numbers when a name is sent.
          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:
      - Numerology
    post:
      operationId: postNumerology
      summary: Life Path and birthday number, plus the name numbers when a name is sent.
      description: 'Pythagorean numerology: Life Path, birthday number and its components, and with a name the expression, soul urge, personality, cornerstone, capstone and hidden passion. Master numbers are kept where the position allows.'
      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.
                name:
                  type: string
                  maxLength: 120
                  description: Optional given name. Without it the name numbers are omitted rather than guessed. Used and discarded; never stored.
                surname:
                  type: string
                  maxLength: 120
                  description: Optional surname, used with the given name where the method uses the full name.
                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: Life Path and birthday number, plus the name numbers when a name is sent.
          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:
      - Numerology
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