Developer APIs · Server-side integration

Readings for your app.

Generate symbolic readings for your own users. The Readings API returns interpretation text alongside calculated evidence, clear disclosures and content versions—ready for your interface.

Get API Keys Read API Docs

Build the experience in your own app. These are API products, not on-site reading tools.

Four reading types. One integration.

Birth-chart readings

Western tropical or Vedic sidereal symbolic themes tied to supported calculation factors. Whole-sign houses; Vedic requests require an explicit ayanamsa.

Compatibility readings

Western synastry or Vedic matching explanations from two birth inputs supplied with permission. Interpretations are not relationship verdicts.

Numerology readings

Bounded Pythagorean number themes, with optional name and personal-year calculations. Name calculations require explicit A–Z transliteration.

Daily, weekly and annual themes

One daily snapshot, seven daily snapshots or twelve monthly snapshots within a calendar year. Sampling can miss events; this is not a continuous forecast.

Text with its evidence intact

English, Hindi and Spanish reading text, calculation references, warnings, versioned content and preset guided explanations. Your application decides how to present and store the result; no saved birth profile is required.

Explicit historical birth inputs and transit samples support 1000 BCE–2500 CE under the documented calendar and time conventions. All samples must remain in range. Review method-specific limits before integrating.

Make a server-side request

Set COSMICEPHEMERIS_API_KEY in your server environment. Require scope astro:symbolic-reading or astro:*. Never put API keys in browser code or mobile apps.

curl https://api.cosmicephemeris.com/api/symbolic/symbolic-reading \
  -H "Authorization: Bearer $COSMICEPHEMERIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "kind": "birth",
  "locale": "en",
  "tradition": "western",
  "birth": {
    "date": "2000-01-01",
    "time": "12:00",
    "timezone": "UTC",
    "lat": 0,
    "lon": 0
  }
}'

Each admitted attempt uses one standard credit, including failed calculations. Plan quotas and key budgets apply. Calls are stateless: results are returned to your application and are not added to saved account history.

Your app owns rendering, storage and report exports. The API does not return an account PDF. Use the supplemental OpenAPI contract for exact inputs and response fields, or the MCP symbolic tool.

SDK integrationCompare plansCreate a free account

Already have saved readings?

Your existing history is retained. Sign in to reopen readings, download their JSON or PDF, or delete individual saved records. Opening and downloading saved readings uses no calculation credit.

Open Saved Readings