Cosmic Ephemeris Developer Platform

R231 is live: 77 standard calculations plus the Pro Nakshatra Timeline are available, with the 500-request Free allowance and globally serial durable jobs.

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 52 calculations: 51 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.

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. Plaintext is shown only when the key is created or rotated; Cosmic Ephemeris stores its SHA-256 digest.

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 Charts 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 beta-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 on the protected Saved Charts and Event Searches page. The dashboard supports create, edit, delete, copy, and JSON export for event types, bodies, aspects, Moon-phase selection, zodiac, ayanamsa, display timezone, aspect-window orb, and grouped passes.

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.

Durable batch jobs

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.

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. It 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 verifyCalculationReceipt in either official SDK. 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 an 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. This is a bounded R196 beta.

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. This is a bounded R197 beta.

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. This is a live beta.

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. This is a live beta.

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. This is a live beta.

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. This is a live beta.

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. This is a live beta.

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. This is a live beta.

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. This is a live beta.

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 R210 contract, migration 043, and candidate clients are source-only and are not live.

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 R209 contract, migration 042, and candidate clients are source-only and are not live.

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 R208 contract, migration 041, and candidate client versions are source-only and are not live.

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 R207 contract, migration 040, and candidate client versions are source-only and are not live.

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 R206 contract, migration 039, and candidate client versions are source-only and are not live.

MCP for trusted agent hosts

POST https://api.cosmicephemeris.com/mcp exposes one stateless tool, cosmicephemeris_calculate, for the 78 live calculations. 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 source MCP inventory also contains the R206 electional robustness, R207 tolerance-frontier, R208 feasibility-audit, R209 resolution-audit, and R210 sampling-phase-audit operations for release testing; it is not available from the live 52-operation service until a separately verified promotion.

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 initialization, tool discovery, request examples, OAuth metadata, errors, and the current protocol revision.

n8n and serverless integrations

The published n8n 0.1.11 package provides sixteen bounded operations: birth chart, natal context, event calendar, event-rule search, convention comparison, chart robustness, civil-time audit, chart-input readiness, house-system readiness, house-placement stability, aspect-policy stability, house-boundary proximity, location-precision audit, location-transition scan, chart uncertainty envelope, and birth-time sensitivity. It accepts a server-side API key credential and does not implement browser credential storage, retries, arbitrary URLs, or model-generated route names.

The current n8n 0.1.37 source covers all 78 live service operations. Registry publication remains separate from service deployment; the last published n8n package is 0.1.11.

Dependency-free AWS Lambda and Cloudflare Worker examples show 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

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.

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 calculation pricing?

No. The same plan and calculation meters apply. Management actions and polling do not consume calculation quota.

Can I expose a key in my browser or mobile app?

No. Keep the key on a trusted backend or agent host and call Cosmic Ephemeris from there.

Does a workspace get its own subscription or quota?

No. Shared keys use the immutable workspace owner's subscription, quota, environment policy, and budgets.

Are asteroid and minor-body calculations included?

No. Those never-live contracts were retired permanently. Fixed stars are a separate live CC0 endpoint.

Next steps

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