Metadata & Utilities

API Metadata

GET /meta/version

Get current API version information.

Some deployments may include additional contract metadata (e.g., a deterministic contract hash) only for authorized callers. Do not rely on optional fields being present unless your account is entitled to them.

Request:

curl https://api.astromcp.io/meta/version \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "version": "1.0.0",
  "title": "Meridian Ephemeris API"
}

Use Cases:

• Version Locking: Pin deployments to specific API versions
• Health Monitoring: Verify correct API version is deployed

---

GET /meta/openapi.json

Return the OpenAPI 3.0 schema for automated client generation.

Request:

curl https://api.astromcp.io/meta/openapi.json \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -o openapi.json

Response: Complete OpenAPI 3.0 JSON specification.

Example Usage:

# Generate TypeScript client
openapi-generator-cli generate \
  -i openapi.json \
  -g typescript-fetch \
  -o src/lib/api

# Generate Python client
openapi-generator-cli generate \
  -i openapi.json \
  -g python \
  -o python-client

---

Configuration Schemas

GET /ephemeris/house-systems

Get list of all supported astrological house systems.

Response:

{
  "house_systems": [
    { "code": "P", "name": "Placidus", "description": "Most popular in modern Western astrology" },
    { "code": "K", "name": "Koch", "description": "Birthplace system" },
    { "code": "W", "name": "Whole Sign", "description": "Traditional Hellenistic system" },
    { "code": "E", "name": "Equal House", "description": "Each house is 30 degrees" },
    { "code": "C", "name": "Campanus", "description": "Space-based system" },
    { "code": "R", "name": "Regiomontanus", "description": "Medieval system" },
    { "code": "O", "name": "Porphyrius", "description": "Ancient system" },
    { "code": "A", "name": "Equal (Ascendant)", "description": "Equal houses from Ascendant" },
    { "code": "V", "name": "Vehlow Equal", "description": "Ascendant at 15° of 1st house" },
    { "code": "B", "name": "Alcabitus", "description": "Medieval Arabic system" },
    { "code": "M", "name": "Morinus", "description": "Equatorial-based system" },
    { "code": "T", "name": "Polich/Page (Topocentric)", "description": "Topocentric house system" }
  ]
}

---

GET /ephemeris/supported-objects

Get list of all supported celestial objects in calculations.

Response:

{
  "planets": [
    { "id": "sun", "name": "Sun", "symbol": "☉", "swiss_id": 0 },
    { "id": "moon", "name": "Moon", "symbol": "☽", "swiss_id": 1 },
    { "id": "mercury", "name": "Mercury", "symbol": "☿", "swiss_id": 2 },
    { "id": "venus", "name": "Venus", "symbol": "♀", "swiss_id": 3 },
    { "id": "mars", "name": "Mars", "symbol": "♂", "swiss_id": 4 },
    { "id": "jupiter", "name": "Jupiter", "symbol": "♃", "swiss_id": 5 },
    { "id": "saturn", "name": "Saturn", "symbol": "♄", "swiss_id": 6 },
    { "id": "uranus", "name": "Uranus", "symbol": "♅", "swiss_id": 7 },
    { "id": "neptune", "name": "Neptune", "symbol": "♆", "swiss_id": 8 },
    { "id": "pluto", "name": "Pluto", "symbol": "♇", "swiss_id": 9 }
  ],
  "asteroids": [
    { "id": "chiron", "name": "Chiron", "swiss_id": 15 },
    { "id": "ceres", "name": "Ceres", "swiss_id": 17 },
    { "id": "pallas", "name": "Pallas", "swiss_id": 18 },
    { "id": "juno", "name": "Juno", "swiss_id": 19 },
    { "id": "vesta", "name": "Vesta", "swiss_id": 20 }
  ],
  "nodes": [
    { "id": "mean_node", "name": "Mean North Node", "swiss_id": 10 },
    { "id": "true_node", "name": "True North Node", "swiss_id": 11 }
  ],
  "points": [
    { "id": "mean_lilith", "name": "Mean Black Moon Lilith", "swiss_id": 12 },
    { "id": "true_lilith", "name": "True/Osculating Lilith", "swiss_id": 13 }
  ]
}

---

GET /ephemeris/supported-metadata

Get supported metadata lookups and enums used across ephemeris and predictive endpoints.

Request:

curl https://api.astromcp.io/ephemeris/supported-metadata \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response: A JSON object containing supported values and metadata catalogs (see OpenAPI for the canonical shape).

---

GET /ephemeris/schemas/natal-request

Get JSON schema for natal chart request format.

Response: JSON Schema definition for request validation.

---

GET /ephemeris/schemas/natal-response

Get JSON schema for natal chart response format.

Response: JSON Schema definition for response parsing.

---

Health Checks

GET /health

Basic health check for the entire API service.

Request:

curl https://api.astromcp.io/health

Response:

{
  "status": "healthy",
  "timestamp": "2024-12-10T12:00:00Z"
}

---

GET /health/detailed

Comprehensive health check with dependency status validation.

Response:

{
  "status": "healthy",
  "timestamp": "2024-12-10T12:00:00Z",
  "version": "1.0.0",
  "services": {
    "ephemeris": {
      "status": "healthy",
      "ephemeris_files_available": true,
      "ephemeris_path": "/app/ephemeris",
      "swiss_version": "2.10.03"
    },
    "database": {
      "status": "healthy",
      "connection_pool_active": 5,
      "connection_pool_max": 20
    },
    "cache": {
      "status": "healthy",
      "redis_connected": true,
      "cache_hit_rate": 0.73
    }
  },
  "uptime_seconds": 86400
}

---

GET /ephemeris/health

Health check specific to the ephemeris calculation service.

Response:

{
  "status": "healthy",
  "ephemeris_available": true,
  "ephemeris_path": "/app/ephemeris",
  "swiss_version": "2.10.03",
  "available_files": ["sepl_18.se1", "semo_18.se1"],
  "calculation_test": "passed"
}

---

GET /predictive/health

Health check for the predictive astrology service.

Response:

{
  "status": "healthy",
  "endpoints_available": [
    "transits/planet-to-degree",
    "transits/sign-ingresses",
    "transits/search",
    "returns/solar",
    "returns/lunar",
    "events"
  ],
  "optimization_enabled": true,
  "cache_enabled": true
}

---

Predictive Service Utilities

GET /predictive/rate-limits

Get current rate limiting information for predictive endpoints.

Response:

{
  "rate_limits": {
    "transits": {
      "requests_per_minute": 60,
      "requests_per_hour": 1000,
      "current_usage": {
        "minute": 12,
        "hour": 245
      }
    },
    "returns": {
      "requests_per_minute": 100,
      "requests_per_hour": 2000
    }
  },
  "quota_reset_at": "2024-12-10T13:00:00Z"
}

---

GET /predictive/optimization/status

Get current performance optimization status and metrics.

Response:

{
  "optimization_enabled": true,
  "cache_size_mb": 256,
  "cache_hit_rate": 0.68,
  "avg_calculation_time_ms": {
    "transit_to_degree": 45.2,
    "sign_ingress": 123.5,
    "solar_return": 67.8
  },
  "parallel_processing": true,
  "worker_threads": 4
}

---

POST /predictive/optimization/clear-cache

Clear performance optimization cache to free memory or reset calculations.

Request:

{
  "cache_type": "transits"
}

Optional cache_type values:

• transits - Clear transit calculations cache
• returns - Clear return calculations cache
• all - Clear all caches

Response:

{
  "success": true,
  "message": "Transit cache cleared successfully",
  "cache_types_available": ["transits", "returns", "progressions"],
  "cleared_entries": 1234,
  "freed_memory_mb": 45.2
}

---

GET /predictive/optimization/benchmarks

Get performance benchmark results and optimization effectiveness.

Response:

{
  "benchmarks": {
    "transit_to_degree": {
      "avg_time_ms": 45.2,
      "p50_ms": 42.1,
      "p95_ms": 78.5,
      "p99_ms": 125.3,
      "samples": 10000
    },
    "sign_ingress": {
      "avg_time_ms": 123.5,
      "p50_ms": 115.2,
      "p95_ms": 189.7,
      "p99_ms": 245.8,
      "samples": 5000
    }
  },
  "optimization_improvement": {
    "cache_enabled": "68% faster on cache hits",
    "parallel_processing": "2.3x speedup on batch operations"
  }
}

---

Integration Examples

CI/CD Version Check

#!/bin/bash
# Check if API schema has changed.
# NOTE: Some deployments only expose `contract_hash` to authorized callers.
# If it's not present, fall back to hashing the downloaded OpenAPI schema.

TOKEN="${TOKEN:-}"
AUTH=()
if [ -n "$TOKEN" ]; then
  AUTH=(-H "Authorization: Bearer $TOKEN")
fi

CURRENT_HASH=$(curl -s "${AUTH[@]}" https://api.astromcp.io/meta/version | jq -r '.contract_hash // empty')
CACHED_HASH=$(cat .api-hash)

if [ -z "$CURRENT_HASH" ]; then
  echo "No contract_hash available; hashing downloaded schema instead."
  curl -s "${AUTH[@]}" https://api.astromcp.io/meta/openapi.json -o openapi.json
  CURRENT_HASH=$(sha256sum openapi.json | awk '{print $1}')
fi

if [ "$CURRENT_HASH" != "$CACHED_HASH" ]; then
  echo "API schema changed, regenerating client..."
  curl -s "${AUTH[@]}" https://api.astromcp.io/meta/openapi.json -o openapi.json
  openapi-generator-cli generate -i openapi.json -g typescript-fetch -o src/lib/api
  echo "$CURRENT_HASH" > .api-hash
fi

Health Check Monitoring

async function checkAPIHealth() {
  const response = await fetch('https://api.astromcp.io/health/detailed');
  const health = await response.json();
  
  if (health.status !== 'healthy') {
    alert('API service degraded');
  }
  
  if (health.services.ephemeris.status !== 'healthy') {
    console.error('Ephemeris service unavailable');
  }
  
  return health;
}

Cache Management

// Clear cache before maintenance window
async function prepareMaintenance() {
  await fetch('https://api.astromcp.io/predictive/optimization/clear-cache', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({ cache_type: 'all' })
  });
}