Make your first request.
Create an account, verify your email, activate an available subscription and create a production API key in your dashboard. Put the key in your server’s secret store.
curl https://api.celestackapi.com/v1/catalog \
-H 'Accept: application/json'The public catalog lists enabled endpoints, preview modules and credit costs. Open the live interactive reference to copy a request that matches the current schema.
curl https://api.celestackapi.com/v1/tarot/readings \
-H "Authorization: Bearer $CELESTACK_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: your-unique-request-id' \
-d '{"spread":"one_card","locale":"en","reversals":true}'Example values are static. Your application should read the returned method and metadata, and should not infer availability from a marketing example.
Two kinds of credentials.
Dashboard: Firebase Authentication with Google, Apple or email and password. The dashboard exchanges a refreshed Firebase ID token with POST /v1/auth/firebase and uses it for account, key and billing management. Email verification is required before production-key issuance.
Application API: Send your production API key in Authorization: Bearer YOUR_API_KEY. Never embed a production key in public browser code, a mobile bundle or a repository.
| Scope | Purpose |
|---|---|
read | Read supported API resources. |
calculate | Make calculation requests. |
uploads | Use enabled private-upload operations. |
reports | Use enabled report operations. |
Full secrets are returned once at creation. Revoke compromised or unused keys from the dashboard. A verified account does not bypass subscription or endpoint gates.
Keep inputs explicit.
Send UTF-8 JSON with Content-Type: application/json. Use ISO dates, explicit timezones and geographic coordinates in the form documented by each endpoint. Do not substitute an assumed noon birth time when the time is unknown.
- Birth-time ambiguity, daylight-saving transitions and unavailable calculations should be handled as explicit outcomes.
- Use idempotency keys where supported by the endpoint. Reuse the same key for an uncertain retry of the same request.
- Asynchronous operations return their own job status. Poll the owned job instead of submitting duplicate work.
- SVG and JSON are different output formats; read the returned content type.
The live schema is the source of truth for payload fields, date ranges, upload limits and optional settings.
Predictable use, with hard limits.
Both standard subscriptions include 50,000 credits per month. Annual billing retains a monthly reset. Credits do not roll over. Heavy operations may cost more than one credit, and gated endpoints cannot be used simply because credits remain.
Standard plans have separate daily limits of 5,000 credits and 5,000 new operation attempts per UTC day, plus 60 authenticated requests per minute. A newly accepted calculation or report attempt counts even if it later fails; replaying the same idempotent operation does not count again. Reading a saved result or polling a job does not create another operation attempt.
Your dashboard uses GET /v1/usage to show credit balances, operation attempts, saved-result usage, rate limits, concurrency and AI attempts.
{
"credits": {"limit": 50000, "used": 0, "reserved": 0,
"remaining": 50000, "resets_at": 0},
"daily": {"limit": 5000, "used": 0, "reserved": 0},
"attempts": {"limit": 5000, "used": 0, "remaining": 5000,
"resets_at": 0, "timezone": "UTC"},
"result_storage": {"retained_bytes": 0,
"organization_limit_bytes": 134217728, "retention_days": 7},
"rate_limit": {"requests_per_minute": 60},
"concurrency": 2
}This is a schema illustration, not account data. The API enforces the actual account values. There are no automatic overage charges. On exhaustion, wait for a reset or request a custom allowance.
Keep control of saved results.
Each organization can retain up to 128 MiB of saved JSON results for up to 7 days. This allowance is shared across its API keys. Export responses your application needs to retain longer. If the allowance is full, new results are rejected until space is available; check GET /v1/usage and delete a saved response you no longer need.
| Request | Required scope | Outcome |
|---|---|---|
GET /v1/operations/{operation_id}/result | read | Returns an owned, completed saved response. Expired or deleted results return 410. |
DELETE /v1/operations/{operation_id}/result | calculate | Releases the saved JSON and returns its released byte count. |
Use the original response’s request_id as operation_id. Deletion does not refund credits or reset usage. Operation and idempotency records remain. A queued or running report that uses the response prevents deletion with 409 result_in_use_by_job. Finish that job before deleting its source. Private artifact links have their own expiry.
Large interpretations contain at most 256 whole source topics selected across the result. Read interpretation.coverage for the full count and omitted count; all calculated numbers remain in data. AI prose and PDF documents disclose their smaller topic selections separately.
Handle the outcome.
| HTTP status | What your application should do |
|---|---|
| 400 / 422 | Correct the input. Do not automatically retry unchanged invalid data. |
| 401 | Check the credential or refresh the dashboard token. |
| 402 / 403 | Check scope, verification, subscription and endpoint entitlement. |
| 404 | Check the API version and resource ownership. |
| 409 | Read the conflict or configuration state before retrying. |
| 410 | The saved result expired or was deleted. Use your exported copy; a new calculation is a new operation. |
| 429 | Check the returned limit, usage reset and Retry-After delay. |
| 503 | Capacity is temporarily unavailable. Honor Retry-After. For saved-result capacity, release an owned saved response or wait for expiry. |
| 5xx | Use bounded retries with backoff. Preserve idempotency for uncertain outcomes. |
Error bodies contain machine-readable details. Use the returned code and message rather than treating every failure as a reason to submit a new job.
Separate language from calculation.
Numeric calculations are language-independent. Interpretive content uses the requested locale only when the module supports it. The public catalog returns the current supported locale list.
Keep the locale in your request and cache identity. Do not relabel text returned in one language as another. A locale being listed does not imply every preview module is released in it.
A stable path forward.
/v1 is the current API family. The catalog advertises current version status. /v2 is a roadmap preview and must not be used as a production integration target until its release is published.
See the changelog for shipped changes and the endpoint catalog for module-specific availability.
Be clear with your users.
Planetary positions and mathematical transformations are calculations. Astrological meanings, tarot, numerology and palm interpretations are symbolic content for entertainment and self-reflection. Do not present them as verified predictions, health assessment or a guarantee of a relationship outcome.
Send personal data only with appropriate permission and a legitimate need. Keep production keys server-side. Private uploads and report artifacts require the ownership, retention and deletion controls specified by their endpoint.
Review our open-source notices, privacy policy and terms before launch.