openephemeris-com API Metadata API

openapi: 3.2.0
info:
  description: '**Open Ephemeris Engine** - Professional Astrological Calculations


    A high-performance REST API for precise astrological chart calculations using the SuperNOVAS / Calceph engine. ## Features


    - 🎯 **Precise Calculations**: SuperNOVAS / Calceph backend (NASA DE440) for astronomical accuracy

    - 🏗️ **Flexible Input Formats**: Support for multiple coordinate, datetime, and timezone formats

    - 🏠 **Seven House Systems**: Placidus (default), Koch, Porphyry, Regiomontanus, Campanus, Equal, and Whole Sign — the complete set, enumerated by `GET /ephemeris/house-systems`

    - ⚡ **High Performance**: Parallel processing and intelligent caching

    - 📊 **Comprehensive Data**: Complete natal charts with planets, houses, angles, and aspects

    - 🔒 **Input Validation**: Robust validation with clear error messages

    - 📖 **OpenAPI Documentation**: Interactive API documentation and schema validation

    - 🪐 **Transit Calculations**: Precise planetary transit timing with retrograde support

    - 📅 **Predictive Features**: Solar/lunar returns, sign ingresses, and future transits

    - 🤖 **Agent-First Design**: Optimized for LLM consumption and autonomous tool use


    ## Agent-First Design


    Open Ephemeris is built from the ground up to be "Agent-First". This means:


    1. **High Information Density**: We provide comprehensive metadata to minimize the need for external lookup. 2. **Optimized Projections**: The `format=llm` parameter converts raw astronomical data into a structure that LLMs can reason about more effectively, reducing token usage while preserving interpretive nuance. 3. **Deterministic Contract**: API responses are versioned and strictly typed to ensure reliable tool-calling for AI agents. ### Output Modes (`format` parameter)


    Endpoints supporting enhanced formatting accept a `format` query parameter:


    - `format=json` (default): The full, raw response schema — every field the endpoint produces, in its complete nested form. Choose it when you need the whole object graph. It does not carry more numeric resolution than `format=llm`: most angular values are serialized as 32-bit floats in both, which quantizes them to at worst about 0.055 arcsec (the step grows with the angle — finest near 0°, coarsest approaching 360°). `format=json` returns more fields, not more decimal places. - `format=llm`: A token-optimized projection. It replaces complex nested objects with flattened, "punchy" descriptions that provide immediate context for an LLM (e.g., automatically including the sign name alongside the degree). ## Authentication


    Open Ephemeris supports several authentication modes:


    1. **JWT tokens (end users)** via Supabase:


    ```http

    Authorization: Bearer

    ```


    2. **User API keys (integrations)** via `X-OpenEphemeris-API-Key`, `X-API-Key`, or `Authorization: Bearer`:


    ```http

    X-OpenEphemeris-API-Key: opene-... ```

    or

    ```http

    Authorization: Bearer opene-... ```


    *Note: Use `X-OpenEphemeris-API-Key` if your infrastructure (e.g. AWS/Azure) intercepts the standard `X-API-Key` header.*


    3. **Service API keys (internal services)** via `X-Service-Key` header:


    ```http

    X-Service-Key:

    ```


    Valid service keys are intended for trusted internal services and

    bypass rate limits. User requests remain subject to tier-based

    rate limiting and usage metering. ## Supported Formats


    ### Coordinates

    - **Decimal degrees**: `40.7128, -74.0060`

    - **DMS strings**: `"40°42''46"N", "74°00''22"W"`

    - **Component objects**: `{"degrees": 40, "minutes": 42, "seconds": 46, "direction": "N"}`


    ### DateTime


    **A datetime that states a clock time must also state its zone.** A

    zone-less clock time is rejected with `400 ambiguous_datetime`; it is not

    assumed to be UTC. An unstated zone moves the Ascendant by roughly 15° per

    hour while every planet keeps its sign, so a guess would be a confident

    wrong answer.'
  title: Open Ephemeris API Metadata API
  version: 1.0.0
servers:
- description: Production
  url: https://api.openephemeris.com
tags:
- description: Discover the API schema and current contract hash. **Free — not metered.**
  name: api-metadata
paths:
  /:
    get:
      description: Welcome endpoint with API information and links to documentation.
      operationId: root__get
      responses:
        '200':
          content:
            application/json:
              schema:
                title: Response Root  Get
                type: object
          description: Successful Response
      security: []
      summary: API Root
      tags:
      - api-metadata
      x-meridian-status: live
      x-meridian-tier: Explorer
      x-meridian-units: 0
  /ephemeris/house-systems:
    get:
      description: Get list of supported astrological house systems
      operationId: get_supported_house_systems_ephemeris_house_systems_get
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: List of supported house systems
        '400':
          description: Bad Request - Input validation failed
        '404':
          description: Not found
        '422':
          description: Unprocessable Entity - Invalid input format
        '500':
          description: Internal Server Error - Calculation failed
      security:
      - bearerAuth: []
      - meridianApiKeyAuth: []
      - apiKeyAuth: []
      - serviceKeyAuth: []
      summary: Get Supported House Systems
      tags:
      - api-metadata
      x-meridian-status: live
      x-meridian-tier: Explorer
      x-meridian-units: 0
  /ephemeris/schemas/natal-request:
    get:
      description: Get JSON schema for natal chart request format
      operationId: get_natal_request_schema_ephemeris_schemas_natal_request_get
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: JSON schema for natal chart requests
        '400':
          description: Bad Request - Input validation failed
        '404':
          description: Not found
        '422':
          description: Unprocessable Entity - Invalid input format
        '500':
          description: Internal Server Error - Calculation failed
      security: []
      summary: Get Natal Chart Request Schema
      tags:
      - api-metadata
      x-meridian-status: live
      x-meridian-tier: Explorer
      x-meridian-units: 0
  /ephemeris/schemas/natal-response:
    get:
      description: Get JSON schema for natal chart response format
      operationId: get_natal_response_schema_ephemeris_schemas_natal_response_get
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: JSON schema for natal chart responses
        '400':
          description: Bad Request - Input validation failed
        '404':
          description: Not found
        '422':
          description: Unprocessable Entity - Invalid input format
        '500':
          description: Internal Server Error - Calculation failed
      security:
      - bearerAuth: []
      - meridianApiKeyAuth: []
      - apiKeyAuth: []
      - serviceKeyAuth: []
      summary: Get Natal Chart Response Schema
      tags:
      - api-metadata
      x-meridian-status: live
      x-meridian-tier: Explorer
      x-meridian-units: 0
  /ephemeris/supported-metadata:
    get:
      description: Get canonical metadata lookups used by calculations (sign elements/modalities, supported enums like dignity systems, house systems, node sources, etc.).
      operationId: get_supported_metadata_ephemeris_supported_metadata_get
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Supported metadata
        '400':
          description: Bad Request - Input validation failed
        '404':
          description: Not found
        '422':
          description: Unprocessable Entity - Invalid input format
        '500':
          description: Internal Server Error - Calculation failed
      security: []
      summary: Get Supported Metadata
      tags:
      - api-metadata
      x-meridian-status: live
      x-meridian-tier: Explorer
      x-meridian-units: 0
  /ephemeris/supported-objects:
    get:
      description: Get list of supported celestial objects in calculations
      operationId: get_supported_objects_ephemeris_supported_objects_get
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Supported celestial objects
        '400':
          description: Bad Request - Input validation failed
        '404':
          description: Not found
        '422':
          description: Unprocessable Entity - Invalid input format
        '500':
          description: Internal Server Error - Calculation failed
      security:
      - bearerAuth: []
      - meridianApiKeyAuth: []
      - apiKeyAuth: []
      - serviceKeyAuth: []
      summary: Get Supported Celestial Objects
      tags:
      - api-metadata
      x-meridian-status: live
      x-meridian-tier: Explorer
      x-meridian-units: 0
  /meta/openapi.json:
    get:
      description: 'Return the OpenAPI schema for automated client generation.


        Used by frontend build processes to generate type-safe API clients.

        Authentication is NOT required for this discovery endpoint to facilitate

        automated toolchain integration.


        Returns:

        OpenAPI 3.0 schema (JSON)'
      operationId: get_openapi_schema_meta_openapi_json_get
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Successful Response
      security: []
      summary: Get Openapi Schema
      tags:
      - api-metadata
      x-meridian-status: live
      x-meridian-tier: Explorer
      x-meridian-units: 0
  /meta/version:
    get:
      description: 'Return current API version and contract hash for cache invalidation.


        Frontend CI uses this to detect schema changes and trigger client regeneration.

        Authentication is not required for this discovery endpoint.'
      operationId: get_api_version_meta_version_get
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Successful Response
      security: []
      summary: Get Api Version
      tags:
      - api-metadata
      x-meridian-status: live
      x-meridian-tier: Explorer
      x-meridian-units: 0
components:
  securitySchemes:
    apiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey
    bearerAuth:
      bearerFormat: JWT/API-Key
      scheme: bearer
      type: http
    meridianApiKeyAuth:
      in: header
      name: X-OpenEphemeris-API-Key
      type: apiKey
    serviceKeyAuth:
      in: header
      name: X-Service-Key
      type: apiKey