Current API Capabilities (B2B)

What you can build

Meridian is a computation-first astrology API: you send validated time + location inputs, and you get precise, structured outputs for charts and forecasting.

Common B2B use cases:

• Chart engines: natal, progressed, relocated charts for apps and CRMs
• Forecasting: transit searches, sign ingresses, and return timing
• Location-aware astrology: timezone resolution + geocoding utilities
• Tooling: schema-driven client generation via OpenAPI

Authentication & security model

The OpenAPI contract supports two authentication modes:

• End-user JWT (Supabase): Authorization: Bearer <jwt>
• API key: X-API-Key: <api_key>

Security best practices for partners:

• Keep tokens/keys in server-side secrets (never ship them in public client apps).
• Use separate credentials per environment (dev/staging/prod) to simplify rotation.
• Treat birth data as sensitive: avoid logging raw request payloads.

Related:

• Authentication & API Keys →
• Error Codes & Rate Limits →

How partners discover and stay in sync

Meridian publishes a live OpenAPI schema and a version endpoint for change detection:

• GET /meta/openapi.json — machine-readable schema (authentication required in production)
• GET /meta/version — version info (optional fields may vary by entitlement)

This enables type-safe client generation and automated compatibility checks in CI.

Operational readiness (what’s in the contract)

• GET /ephemeris/health — ephemeris service health probe
• GET /health and GET /health/detailed — global service health probes

Batch compute limits (schema-enforced)

Batch natal chart computation supports up to 100 subjects per request (see NatalBatchRequest.items.maxItems = 100 in the OpenAPI schema).

Supported ephemeris date range

Meridian supports ephemeris calculations for years 1–3000.

Endpoint capability map

This is not an exhaustive list, but it reflects the major capability surfaces exposed in the current schema.

Core ephemeris (charts)

• POST /ephemeris/natal-chart — full natal chart output
• POST /ephemeris/relocation — relocate a chart to new coordinates
• POST /ephemeris/progressed — secondary progressions
• POST /ephemeris/natal/batch — batch chart computation
• GET /ephemeris/house-systems — supported house systems
• GET /ephemeris/supported-objects — supported bodies/points

Lunar-focused utilities

Moon-specific endpoints support operational “daily use” features:

• moon phase
• void-of-course windows
• lunar ingresses
• moon aspects

See Calculations → for moon-related coverage.

Predictive (forecasting)

• POST /predictive/transits/search — search for transit events across a range
• POST /predictive/transits/planet-to-degree — precise degree crossing timing
• POST /predictive/transits/sign-ingresses — ingress timing (single or batch)
• POST /predictive/returns — nearest return timing near a target instant

Location & timezone

• GET /location/autocomplete — typeahead suggestions with coordinates/timezone
• GET /location/reverse — reverse geocode coordinates to place + timezone
• POST /timezone/lookup — resolve IANA timezone from coordinates
• POST /timezone/offset — UTC offset at an instant (DST-aware)

API keys (control plane)

API key management is handled in the AstroMCP dashboard; the underlying endpoints are not part of the marketing/public endpoint list.

Response shaping

Many compute endpoints support consistent query parameters like:

• verbosity
• include_metadata
• metadata_level

These options help partners choose between minimal payloads and richer metadata for support workflows.

Using Endpoints

The AstroMCP dashboard includes an interactive Endpoints page at /dashboard/endpoints:

• Browse available endpoints grouped into Ephemeris, Predictive, Location/Timezone, and Schemas/Metadata.
• Run requests and inspect structured responses.
• Keep a local request history for repeatable debugging.

For deeper endpoint-by-endpoint detail, start here:

• API Endpoints Overview →
• Endpoints Index →