Cosmic Ephemeris Developer Platform

All 78 documented calculations are live: 77 standard calculations are available on every plan, and Pro adds Nakshatra Timeline. Free includes 500 standard requests per UTC calendar month. Durable jobs execute one at a time across the service.

Use the calculation API as a production platform: separate projects and environments, protect budgets, save reusable chart inputs, share keys with a team, run durable jobs, receive signed completion events, export deterministic files, or connect a trusted MCP host.

Production serves 78 calculations: 77 standard operations on every plan plus the separately entitled Pro Nakshatra Timeline. Retired minor-body calculations are not part of the platform and there is no second pricing meter.

Open the complete examples catalog for a copy-paste curl request and schema-validated successful response for every calculation, including each advanced electional audit.

Choose the correct access model

  • API key: server-to-server calculations, durable job submission and polling, and MCP. Send Authorization: Bearer YOUR_API_KEY or X-API-Key.
  • Dashboard session: API-key management, environment policies, saved chart profiles, workspaces, webhook destinations, billing, and account settings. The Secure, HttpOnly cookie is not a calculation credential.
  • Browser and mobile clients: call your own backend. Never embed an Cosmic Ephemeris key in client code, a URL, analytics, or model-visible text.

See Authentication and API Keys for credential lifecycle, dashboard sessions, errors, and a complete signed-webhook verification example.

Projects, environments, scopes, and budgets

Each account can keep up to five active keys. A key can have a unique label, project label, development, staging, or production environment, exact calculation scopes or astro:*, optional expiration, and an optional monthly standard-unit budget. The full plaintext is shown only when the key is created or rotated; the production database stores its SHA-256 digest and first eight characters as a display prefix, not a recoverable full key.

Account-wide environment policies can independently enable standard calculations, Nakshatra Timeline, and batch jobs, and can set one aggregate standard-unit budget across every key in that environment. Environment and per-key budgets are inner guardrails: they never add units beyond the account plan. Timeline uses its separate Pro allowance and does not consume the standard environment budget.

Configure these controls on the protected API Keys dashboard and inspect per-key and environment totals on Usage.

Saved chart profiles

Any active account can store up to 50 reusable birth-input profiles on the protected Saved Inputs page. A profile stores a label, civil birth input, coordinates, zodiac/ayanamsa choice, and one supported house-system choice. It stores no calculation result, image, report, interpretation, or credential.

Creating, reading, replacing, deleting, and JSON-exporting profiles uses the dashboard session and no calculation quota. Saving validates the reusable structure but does not run the engine or guarantee that a later DST, polar, or supported-house calculation will succeed. Profiles remain private to their owning account and are not shared into workspaces.

Saved event searches

Any active account can store up to 25 reusable versioned event-calendar or event-rule-search criteria records through the protected management API. The Saved Inputs page creates and edits calendar criteria and safely displays API-created rule records for copy, export, scheduling, and deletion; rule creation and editing remain API-managed.

A saved search stores no UTC interval, event result, notification destination, or credential. Saving and managing criteria does not run a calculation or use quota. Each later request adds an explicit bounded UTC interval and uses the selected operation’s ordinary API-key scope, quota, and accounting controls.

Customer-defined Event Intelligence rules

POST /api/astro/event-rule-search evaluates a bounded, versioned AND/OR rule tree over Cosmic Ephemeris facts: body sign, direct/retrograde motion, Moon phase, Ascendant sign, and configured major aspects with an orb from 0.1° through 10°. Trees are limited to depth 4, 15 total nodes, and 8 predicates. Searches cover at most seven days on an explicit 15-, 30-, or 60-minute grid.

validate_only:true returns validation and a deterministic sample/cost estimate without scanning the interval, but it is still one admitted calculation unit. Full searches return matching samples, bounded intervals, optional iCalendar, the rule version, and model metadata. Results are grid observations—not continuous-event guarantees, rankings, interpretations, or advice.

Secure calendar subscriptions

An account may create up to 25 revocable read-only subscriptions for enabled saved event-calendar schedules. The protected /api/calendar-subscriptions management API uses the dashboard session. A 256-bit token is disclosed only on creation or rotation; Cosmic Ephemeris stores only its SHA-256 digest. Expiration is explicitly 30, 90, 180, or 365 days.

The public /calendar/subscriptions/<token>.ics and .json URLs return only the latest successful globally serial scheduled-job result. Fetching a feed never starts a calculation. Responses support ETag, If-None-Match, Last-Modified, five-minute private caching, rotation, revocation, and bounded rate limits. Treat the URL as a bearer secret; do not put it in logs, analytics, or public pages.

Team workspaces and shared keys

An account can own up to three workspaces, each with one immutable owner and up to twenty non-owner members. Owners and admins manage invitations and membership; owners, admins, and developers manage shared keys; viewers have read-only workspace/key metadata and usage access.

Invitations are email-bound, expire after seven days, and use a one-time token whose digest is stored. Resending rotates the token. A shared key is billed to the workspace owner and inherits that owner's plan, account quota, environment policy, and key budget. A workspace is not a separate subscription, quota pool, saved-chart tenant, or billing account, and membership never exposes the owner's personal keys, saved charts, dashboard, or billing portal.

Create and manage teams on the protected Team Workspaces page.

Scheduled event searches

Each saved event search can have one daily or weekly UTC schedule. Select an eligible API key, a quarter-hour run time, and a forward window of 24, 72, or 168 hours on the dashboard. Accounts can hold at most ten schedules.

A due schedule enqueues the saved search’s fixed event-calendar or event-rule-search operation. It does not calculate in the scheduler or bypass the selected key's exact scope, environment policy, budget, account quota, job cap, result retention, or one-unit-per-item accounting. Jobs remain globally serial.

Existing signed job.completed webhooks deliver completion metadata. Scheduled criteria and result payloads are not copied into webhook bodies; fetch the key-bound durable job through the normal job API.

Astrological Event Intelligence describes the complete search, save, schedule, export, and delivery workflow.

Durable batch jobs

POST https://api.cosmicephemeris.com/api/jobs accepts one to ten mixed items from fourteen fixed operations: birth-chart, natal-analysis, panchang, vargas, vimshottari, planetary-hours, lunar-nodes, moon-phases, planetary-events, house-ingresses, aspect-windows, event-calendar, event-rule-search, and natal-report. Every admitted item uses the same API key, exact operation scope, environment policy, key budget, and account quota as its synchronous call.

curl https://api.cosmicephemeris.com/api/jobs \
  -X POST \
  -H "Authorization: Bearer $COSMICEPHEMERIS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: charts-20260925-001" \
  -d '{"items":[{"operation":"birth-chart","input":{"date":"2000-01-01","time":"12:00","timezone":"UTC","lat":0,"lon":0}}]}'

Bulk tools can send the same item objects one per line to POST /api/jobs/import with Content-Type: application/x-ndjson and --data-binary @jobs.ndjson. Imports are strict UTF-8, 1–10 non-empty lines, and at most 32 KiB. CSV, multipart, compressed content, remote URLs, blank lines, and BOM-prefixed files are rejected. Cosmic Ephemeris stores no upload name or original file bytes.

  • The required idempotency key is 8–128 characters using letters, digits, period, underscore, colon, or hyphen. An identical replay returns the existing job; different content returns 409.
  • GET /api/jobs lists the newest 20 unexpired jobs created by the exact authenticated API key; detail, replay, and cancellation require that same key. A different or rotated key cannot access the original job.
  • At most ten queued/running jobs exist per account. Inputs and results expire after 24 hours.
  • Moon-phase, planetary-event, house-ingress, aspect-window, event-calendar, and event-rule-search jobs preserve their synchronous search bounds and use fixed 30-second worker timeouts. Natal-report jobs preserve fact-only output and a fixed 15-second timeout.
  • Every item retains the existing 256 KiB stored-result limit.
  • Each item reserves one standard unit immediately before execution. Submission, polling, idempotent replay, and cancellation add no units.
  • JSON and NDJSON use the same key-bound idempotency namespace and semantic request digest, validators, scopes, environment controls, key budget, account quota, serial execution, and 24-hour retention.

Signed job-completion webhooks

A signed-in account can configure up to five HTTPS destinations on the protected Job Webhooks page. Cosmic Ephemeris sends one metadata-only job.completed event after an owned job becomes succeeded, partial, failed, or cancelled. The payload includes a status path but no job input, calculation result, API key, account email, or signing secret.

Verify X-Cosmic-Ephemeris-Signature as HMAC-SHA256 over <timestamp>.<exact raw body>, enforce a short timestamp tolerance, and deduplicate with X-Cosmic-Ephemeris-Event-Id. Any 2xx succeeds; other outcomes retry on a bounded schedule for at most eight attempts. Cosmic Ephemeris follows no redirects and revalidates public-only IPv4 DNS for every attempt. The protected dashboard provides 25-hour, metadata-only delivery history with bounded cursor pagination; viewing it does not consume calculation quota.

Deterministic downloads and uncertain birth times

  • Supported chart routes can return an opt-in deterministic PNG with dimensions, byte count, and SHA-256 while remaining one standard calculation.
  • Calendar-capable routes can return bounded iCalendar text inside JSON. Decode or save the documented value, not the surrounding response.
  • /api/astro/natal-report can return integrity-checked deterministic HTML, Cosmic Ephemeris-branded PDF, editable macro-free DOCX, formula-free and macro-free fixed-column XLSX or ODF 1.3 ODS workbooks, offline script-free EPUB 3, editable macro-free ODF 1.3 ODT, editable dependency-free RTF, machine-readable schema-bound JSON, fixed-column CSV, fixed-order schema-identified XML, canonical one-record-per-fact NDJSON, escaped fixed-column TSV, UTF-8 Markdown, line-oriented UTF-8 plain text, or the fixed ZIP containing HTML, PDF, and calculation JSON. Optional report_branding adds only an escaped display name and one fixed accent to HTML; it accepts no logo, URL, markup, template, or remote resource and is invalid for every non-HTML format. The output is a calculation-fact report, not generated interpretation or advice.
  • /api/astro/birth-time-sensitivity accepts exact intervals or explicit unknown/approximate workflows. It reports sample distributions, stable and variable signs, houses, angles and aspects, plus observed transition boundaries refined to one-second precision. The scan remains bounded and non-exhaustive; ratios are sample observations, not confidence scores, and the route does not select a birth time, rectify, predict, or guarantee an unsampled interval.

Use the report, birth-time workflow, charting, and endpoint-specific calendar guides for their exact schemas and limits.

Publicly verifiable calculation receipts

Send X-Cosmic-Ephemeris-Receipt: v1 on a calculation to embed an Ed25519 receipt binding the normalized request digest, complete result digest, route, release, calculation profile, dataset versions, fingerprint, key ID, and issue time. Retrieve active and retained public keys from /.well-known/jwks.json and verify locally with Node verifyCalculationReceipt or Python verify_calculation_receipt. No shared verification secret is required.

Receipt canonicalization uses the documented cosmicephemeris-canonical-data-v1 typed byte representation, including IEEE-754 binary64 number encoding, so Node and Python verify the same payload. Rotate signing keys by retaining the old public JWK in the trusted key archive. A valid receipt proves integrity and possession of a Cosmic Ephemeris signing key; it does not prove an interpretation, scientific validity, customer identity, wall-clock existence of an external event, or that an unsigned response came from Cosmic Ephemeris.

Convention and release comparison

POST /api/astro/convention-compare can calculate one birth input under exactly two distinct explicit convention profiles and return bounded field-level differences. Profiles cover tropical or sidereal zodiac, the admitted ayanamsas, and Equal, Whole Sign, or Placidus houses. The result describes differences without declaring a winner or adding interpretation.

Unknown-time and convention robustness

POST /api/astro/chart-robustness evaluates the same shared UTC sample grid under two or three explicit convention profiles and classifies 22 planet-sign, planet-house, Ascendant-sign, and Midheaven-sign facts as stable, time-sensitive, convention-sensitive, or sensitive to both. Unknown time uses 25 samples across the complete local civil day; approximate time accepts a 10–120 minute range in ten-minute increments. Evidence is sampled and non-exhaustive: the route does not rectify, choose a time, rank conventions, interpret, predict, or provide statistical confidence.

Release mode accepts exactly two valid trusted receipt-bearing responses for the same route and normalized input, requires different release IDs, and returns at most 500 differences. It compares retained signed outputs; it does not claim to reproduce releases from before receipts existed or silently recalculate historical software.

Civil-time chart audit

POST /api/astro/civil-time-audit resolves one pinned place and local time without guessing. A repeated clock time returns both valid UTC chart candidates and exact changes across 22 sign/house facts; a nonexistent time returns no chart and is never shifted. The profile is explicit, work is capped at two chart evaluations, and the route performs no rectification, interpretation, prediction, persistence, or request-time network call. The calculation is available under the documented bounds.

Chart-input readiness

POST /api/astro/chart-input-readiness accepts a pinned place, an exact, approximate, or unknown birth-time workflow, and one explicit profile. It returns machine-readable route readiness, reason codes, next actions, and at most 22 resolved, candidate, or sampled facts without choosing a fold, shifting a gap, inventing a clock time, rectifying, interpreting, or predicting. Approximate and unknown-time evidence is bounded sampling rather than statistical confidence. The calculation is available under the documented bounds.

House-system readiness

POST /api/astro/house-system-readiness evaluates the fixed 25-system house inventory for one exact birth. It reports per-system availability, 12- or 36-sector count, deterministic cusp fingerprints, and Houses/natal-SVG readiness. Undefined polar geometry remains an explicit failure and no fallback system is selected. The calculation is available under the documented bounds.

House-placement stability

POST /api/astro/house-placement-stability reports exact ten-planet house assignments across every available twelve-house system in the fixed inventory, with unweighted agreement ratios and deterministic placement-group fingerprints. Gauquelin is explicitly excluded, undefined polar geometry remains unavailable, and no fallback, ranking, recommendation, rectification, interpretation, prediction, or confidence claim is made. The calculation is available under the documented bounds.

Aspect-policy stability

POST /api/astro/aspect-policy-stability calculates one exact chart and compares two to four caller-declared aspect policies across three to ten selected planets. It returns every candidate admitted by at least one policy, exact separation and orb, admitted, outside_orb, or not_configured per policy, signed boundary margins, SHA-256 aspect-set fingerprints, and deterministic equivalence groups. All-rejected candidates are intentionally omitted. Policies are unweighted and the response makes no strength, confidence, ranking, recommendation, interpretation, prediction, or practitioner-preference claim. The calculation is available under the documented bounds.

House-boundary proximity

POST /api/astro/house-boundary-proximity measures one to ten selected planets against every available 12-house system in the fixed inventory. It returns the assigned house, preceding and following cusp longitudes, exact two-sided clearance, normalized within-house position, tie-preserving nearest cusps, and inclusive caller-threshold flags. Undefined geometry remains explicit, Gauquelin is excluded, and no fallback, reassignment, ranking, recommendation, interpretation, or prediction occurs. The calculation is available under the documented bounds.

Location-precision audit

POST /api/astro/location-precision-audit calculates one exact birth moment at the supplied coordinates and eight equal-bearing perimeter samples on a declared 0.1–500 km spherical radius for one explicit 12-house system. It returns every sample coordinate and availability, selected-planet house stability, and maximum Ascendant, Midheaven, and cusp displacement from the center. The samples do not guarantee the unsampled disk or provide statistical confidence; undefined geometry stays explicit, Gauquelin is excluded, and no fallback, geocoding, rectification, ranking, interpretation, or prediction occurs. The calculation is available under the documented bounds.

Location-transition scan

POST /api/astro/location-transition-scan calculates the center plus eight equal radial checkpoints on each of eight fixed bearings up to 1–500 km. For Ascendant sign, Midheaven sign, all cusp signs, and selected planet houses, each bearing reports the first observed checkpoint bracket, no observed transition, or explicit unavailable geometry. A bracket is not an exact crossing and cannot guarantee intermediate transitions or the unsampled disk. No fallback, geocoding, score, ranking, recommendation, rectification, interpretation, or prediction occurs. The calculation is available under the documented bounds.

Chart uncertainty envelope

POST /api/astro/chart-uncertainty-envelope resolves one exact civil center, then calculates seven exact UTC instants against the center plus eight perimeter coordinates as a fixed 63-chart full-factorial matrix. It returns traceable values and observed attribution for Ascendant/Midheaven signs, all cusp signs, and selected planet signs and houses across the time axis, location axis, full matrix, and combined-only interactions. This sampled evidence does not prove continuous-time stability or the unsampled disk and performs no rectification, statistical confidence, causal attribution, fallback, ranking, recommendation, interpretation, or prediction. The calculation is available under the documented bounds.

Electional sampling phase audit

POST /api/astro/electional-sampling-phase-audit evaluates one fixed 15-minute UTC grid and projects those same samples across both 30-minute phases and all four 60-minute phases measured from request start. It reports which observed matching runs every phase witnesses, which depend on the grid anchor, and exact phase offsets plus finest-grid witnesses. This is sampled evidence, not probability or continuous-time proof. This operation is included in the 78-calculation service and canonical SDKs.

Electional resolution audit

POST /api/astro/electional-resolution-audit evaluates one fixed 15-minute UTC grid and projects the same evidence to aligned 30- and 60-minute checkpoints. It identifies every contiguous observed finest-grid matching run, whether each coarser grid witnessed it, and exact witness samples for missed runs. Run boundaries are not interpolated and unsampled instants are not evaluated. This operation is included in the 78-calculation service and canonical SDKs.

Electional feasibility audit

POST /api/astro/electional-feasibility-audit evaluates a fixed 15, 30, or 60 minute UTC grid over at most seven days. It returns exact passed/failed rules per sample, per-rule match and blocking ratios, all observed blocking signatures, and inclusion-minimal failed-rule sets with exact witness samples. It is sampled evidence, not continuous proof, causal diagnosis, weighting, ranking, recommendation, interpretation, prediction, or statistical confidence. This operation is included in the 78-calculation service and canonical SDKs.

Electional tolerance frontier

POST /api/astro/electional-tolerance-frontier walks outward through ten samples earlier and later and along ten distances on each of eight venue bearings. Each selected electional rule returns its last observed match, first observed failure, first unavailable point, and traceable sample IDs. The 101-chart bounded audit makes no interpolation, exact-boundary, monotonicity, entire-disk, statistical, ranking, recommendation, interpretation, or prediction claim. This operation is included in the 78-calculation service and canonical SDKs.

Electional robustness audit

POST /api/astro/electional-robustness-audit stress-tests one selected event over seven exact UTC instants and the center plus eight perimeter coordinates. It returns a fixed 63-sample full-factorial matrix and attributes each requested Moon-sign, phase, Mercury-motion, Ascendant-sign, or aspect rule's observed failures to time, location, both axes, or combined-only samples. It makes no continuous-time, entire-disk, causal, statistical, ranking, recommendation, interpretation, or prediction claim. This operation is included in the 78-calculation service and canonical SDKs.

Tarot, symbolic readings and supplemental Vedic systems

Three separate generation APIs complement the original calculation catalog: POST /api/symbolic/tarot, POST /api/symbolic/symbolic-reading and POST /api/symbolic/vedic-systems. Use narrowly scoped server-side credentials; each admitted generation uses one standard credit. The Vedic systems route includes Yogini periods, regional factors and named North/South festival calendars.

Node/Python 0.5.0 is published on npm/PyPI and includes these three methods. Use the SDKs, documented HTTP requests or the live cosmicephemeris_symbolic MCP tool. Upgrade older packages to access the supplemental methods. Private saved readings and server-generated PDFs remain account-session features, not SDK/MCP or batch operations. Supplemental schemas, scopes and examples.

MCP for trusted agent hosts

POST https://api.cosmicephemeris.com/mcp exposes two stateless tools: cosmicephemeris_calculate for the 78 live calculations and cosmicephemeris_symbolic for the three supplemental APIs. The adapter rejects browser Origin headers and accepts no caller-controlled URL, arbitrary route, prompt, file, or credential argument. Every tool call passes through the selected calculation's existing key scope, plan, quota, concurrency, environment, and budget checks.

The live MCP inventory covers all 78 calculations, including electional robustness, tolerance-frontier, feasibility, resolution, and sampling-phase audits, under the same per-route access, quota, and timeout controls.

Remote MCP also supports MCP confidential client credentials at /oauth/token. Use the API-key UUID as client_id, the raw API key as client_secret, and the exact resource https://api.cosmicephemeris.com/mcp. Tokens are opaque, expire after five minutes, can only narrow the key’s live scopes, and are rejected if replayed directly against REST calculations. This is machine-to-machine authorization, not browser login, user delegation, dynamic client registration, or an authorization-code flow.

Use the MCP Server guide for server discovery, tool discovery, request examples, OAuth metadata, errors, and the current protocol revision.

n8n and serverless integrations

The published canonical n8n-nodes-cosmicephemeris 0.2.1 package provides 42 bounded connector operations over the 78-calculation service, with server-side API-key credentials and fixed operation names. It does not implement browser credential storage, automatic retries, or caller-controlled URLs.

Download the dependency-free AWS Lambda example or Cloudflare Worker example. Each shows a receipt-enabled birth-chart proxy with strict JSON, 128 KiB request and 32 MiB response limits, a 20-second timeout, no redirects, no retries, safe errors, and a secret-store API key. They are starting points that customers must deploy and monitor in their own accounts.

Plans, quota, and feature access

PlanMonthly calculation allowancePlatform tools
Free500 standard unitsIncluded
Developer — $9.99/month10,000 standard unitsIncluded
Pro — $19.99/month100,000 standard units plus 1,000 Nakshatra Timeline unitsIncluded

Production includes 77 standard calculations on all plans and the Pro Nakshatra Timeline, for 78 live calculations. An admitted synchronous request, MCP tool calculation, or batch item uses the selected route's normal unit even if a later validation, calculation, or timeout failure occurs. Saved charts, workspace administration, key/environment management, webhook management, job submission/polling/replay/cancellation, OpenAPI, Postman, and client libraries do not consume calculation units.

Deleting an account or changing its email does not reset the current month's free allowance. Addresses linked by a verified email change share the remaining free allowance for that UTC month. The usage dashboard includes this shared usage. Paid plan limits remain per account; API-key rotation never resets account usage.

The November 8 free-allowance update adds no terms-acceptance prompt for existing users: you can continue signing in and using the service. New accounts follow the same signup acceptance and email-verification steps. Free still includes 500 standard requests per UTC calendar month.

Each account can run up to 2 calculations concurrently, maintain 5 active API keys and 50 saved chart profiles, and queue up to 10 active batch jobs containing 10 items each. Monthly plan quotas still apply.

These workflow additions fit the current pricing model; no separate platform add-on is required. See Pricing for billing terms and the complete standard-route inventory.

Availability and licensing boundary

The platform features on this page are live and require no purchased proprietary data license or individually granted publishing permission. The six-star fixed-star route uses separately reviewed CC0 source data. The never-live minor-body contracts and their activation paths were permanently retired and are not included in the API contract, SDKs, live count, or pricing promise.

Common questions

Do platform tools change Cosmic Ephemeris calculation pricing?

No. Saved charts, workspace management, webhook management, and job polling do not consume calculation quota. Each admitted synchronous calculation, MCP calculation, or batch item uses the same applicable standard or timeline unit.

Can a Cosmic Ephemeris key be used safely in a browser or mobile app?

No. Cosmic Ephemeris keys are server-side credentials. Store them in a backend environment or secret manager and never place them in browser JavaScript, mobile bundles, URLs, prompts, or analytics.

Do team workspaces create a separate subscription or quota pool?

No. A shared workspace key uses the immutable workspace owner's plan, account quota, environment policy, and key budget. Membership does not grant access to the owner's account, billing, saved charts, or personal keys.

Are minor-body and asteroid calculations included?

No. The never-live minor-body contracts were permanently retired rather than depend on licensed source data. The six-star CC0 fixed-star endpoint is separate and live.

Next steps

  1. Create a least-privilege key from the API Keys area of your dashboard and store it in a server-side secret manager.
  2. Choose an endpoint from the calculation reference, or use OpenAPI, Postman, the Node client, or the Python client.
  3. Add jobs, webhooks, workspaces, saved profiles, or MCP only where the integration needs them.