AstroAPI Developer Platform

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.

These tools are live and use the existing AstroAPI plans. They add workflow and access controls around the same 35 calculations; they do not activate the unavailable JPL minor-body routes or add a 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 AstroAPI 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; AstroAPI 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.

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

POST https://api.astroapi.io/api/jobs accepts one to ten mixed items from birth-chart, natal-analysis, panchang, vargas, vimshottari, planetary-hours, and lunar-nodes. It uses the same API key, exact operation scope, environment policy, key budget, and account quota as a synchronous call.

curl https://api.astroapi.io/api/jobs \
  -X POST \
  -H "Authorization: Bearer $ASTROAPI_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}}]}'

• 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; GET /api/jobs/{id} returns ordered states/results; DELETE /api/jobs/{id} requests cancellation.
• At most ten queued/running jobs exist per account. Inputs and results expire after 24 hours.
• Each item reserves one standard unit immediately before execution. Submission, polling, idempotent replay, and cancellation add no units.

Signed job-completion webhooks

A signed-in account can configure up to five HTTPS destinations on the protected Job Webhooks page. AstroAPI 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-AstroAPI-Signature as HMAC-SHA256 over <timestamp>.<exact raw body>, enforce a short timestamp tolerance, and deduplicate with X-AstroAPI-Event-Id. Any 2xx succeeds; other outcomes retry on a bounded schedule for at most eight attempts. AstroAPI 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 standalone HTML download bytes. 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 sampled stability and variability; it does not select an exact time or perform rectification.

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

MCP for trusted agent hosts

POST https://api.astroapi.io/mcp exposes one stateless tool, astroapi_calculate, for the 35 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.

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

Plans, quota, and feature access

All plans include the 34 standard calculations. Pro also includes Nakshatra Timeline, for 35 live calculations total. 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 do not require a new third-party data license. The six-star fixed-star route uses separately reviewed source data. Three JPL minor-body contracts remain fail-closed and return unavailable until written permission, provider-artifact admission, and their remaining acceptance gates pass; they are not included in the 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 AstroAPI 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 three contracts remain unavailable behind separate permission and artifact gates. Fixed stars are a separate live 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.