openephemeris-com Health 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 Health API
  version: 1.0.0
servers:
- description: Production
  url: https://api.openephemeris.com
tags:
- description: System health and readiness checks. **Free — not metered.**
  name: Health
paths:
  /health:
    get:
      description: Basic health check for the entire API service.
      operationId: global_health_check_health_get
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Successful Response
        '503':
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Service Unavailable - readiness check failed
      security: []
      summary: Global Health Check
      tags:
      - Health
      x-meridian-status: live
      x-meridian-tier: Explorer
      x-meridian-units: 0
  /health/detailed:
    get:
      description: Health check that runs internal calculation self-tests (nakshatra, HD gates, Venus phase, aspects, harmonics, profections, firdaria, zodiacal releasing) plus one true external dependency check (the loaded ephemeris engine).
      operationId: detailed_health_check_health_detailed_get
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Successful Response
        '503':
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: Service Unavailable - readiness check failed
      security: []
      summary: Detailed Health Check
      tags:
      - Health
      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