AstroCompass
Log InSign Up

AstroMCP API

Chart calculation, horoscopes, tarot, and account management, all as a REST API. This reference documents every endpoint the AstroMCP API currently exposes.

astromcp.com is not live yet; you're reading this on the AstroCompass hub instead. Base URLs and a self-service key flow will move here once that domain is deployed.

Authentication

Every endpoint below except the ones marked "No auth required" expects your API key as a bearer token:

Authorization: Bearer <your-api-key>

Every error response, from any endpoint, shares one shape:

{
  "error": {
    "code": "SOME_ERROR_CODE",
    "message": "Human-readable explanation."
  }
}

Health

GET/healthNo auth required

Liveness probe for the distributor, plus a downstream health check of the supplier service.

Response: { status: "ok"|"degraded", service: "distributor", version, timestamp, upstream: { supplier: "ok"|"unreachable", supplierDiagnostics } }: always HTTP 200; read `status` for degraded state.

API Keys

Every endpoint below except the first requires the Authorization header described in Authentication.

POST/v1/keysNo auth required

Create an API key. Unprotected by design (it's how you get your first key), tier is clamped to free unless the caller already has authority for a higher tier.

Request: { name: string, tier?: "free"|"starter"|"growth"|"scale"|"enterprise", tenantId?: uuid }

Response: 201 { key, prefix, name, tier, createdAt }: `key` is the raw secret, shown exactly once and never retrievable again.

GET/v1/keys/meAPI key required

Look up your own key record.

Response: 200: your ApiKeyRecord.

GET/v1/keysAPI key required (enterprise tier)

List every API key (admin surface).

Response: 200 { keys: [{ id, name, keyPrefix, tier, isActive, createdAt, lastUsedAt }] }: the key secret itself is never returned.

DELETE/v1/keys/:idAPI key required (enterprise tier)

Revoke a key. Irreversible.

Response: 204 on success, 404 if no such key.

Chart Data

All chart/horoscope/tarot endpoints are metered and, where noted, cached: repeat requests for the same inputs within the cache window return the cached result.

POST/v1/chart/natalAPI key required

Compute a full natal chart for a birth date, time, and location. Cached 7 days per input.

Request: { year, month, day, hour?, minute?, second?, latitude, longitude, houseSystem?, locale? }

Response: { julian_day, planets[], houses[], ascendant, aspects[] }

GET/v1/planets/currentAPI key required

Real-time current planetary positions. Cached 1 hour.

Response: { julian_day, planets[] }

GET/v1/horoscope/:sign/dailyAPI key required

Daily horoscope for a zodiac sign. Cached 24 hours.

Request: params: sign. query: date?, locale?

Response: { sign, period, content: { title, body, theme } }

GET/v1/horoscope/:sign/weeklyAPI key required

A week-ahead overview plus each individual day's reading for that week.

Request: params: sign. query: date?, locale?

Response: { sign, period: "weekly", week_start, week_end, overview, days[] }

GET/v1/horoscope/:sign/monthlyAPI key required

Monthly horoscope for a sign. Cached per calendar month.

Request: params: sign. query: date?, locale?

Response: { sign, period, content: { title, body, theme } }

GET/v1/tarot/dailyAPI key required

The shared daily tarot advice card: one card for every caller that day. Cached 24 hours.

Request: query: date?, locale?

Response: { spread_type, generated_at, cards[], summary }

GET/v1/tarot/weeklyAPI key required

The shared weekly tarot reading. Cached 7 days.

Request: query: date?, locale?

Response: { spread_type, generated_at, cards[], summary }

GET/v1/tarot/monthlyAPI key required

Monthly tarot reading composed from that month's weekly readings. Cached 31 days.

Request: query: date?, locale?

Response: { spread_type: "monthly", generated_at, cards[], summary }

POST/v1/tarot/readingAPI key required

An on-demand personal tarot draw. Never cached: every draw is unique.

Request: { spreadType: "single"|"three_card"|"celtic_cross", allowReversals?, question?, locale? }

Response: Opaque reading object (shape varies by spread type).

Analytics

Admin-portal surfaces, not general third-party endpoints: every route here requires an enterprise-tier key.

GET/v1/analytics/summaryAPI key required (enterprise tier)

Headline usage metrics for a time window.

Request: query: range? (24h|7d|30d, default 24h)

Response: { totalRequests, cacheHitRate, uniqueKeys, avgLatencyMs, requestsByTier[], requestsByStatus[] }

GET/v1/analytics/timeseriesAPI key required (enterprise tier)

Chartable request/cache-hit volume over time.

Request: query: range?

Response: { buckets: [{ timestamp, requests, hits }] }

GET/v1/analytics/top-keysAPI key required (enterprise tier)

Busiest API keys by request count.

Request: query: range?, limit? (default 10, max 100)

Response: { keys: [{ keyId, keyName, prefix, tier, requests, cacheHits }] }

Tenants

Admin-only white-label tenant management, enterprise tier required.

GET/v1/tenantsAPI key required (enterprise tier)

Paginated, searchable, sortable white-label tenant list.

Request: query: page?, limit? (max 100), q?, sort?, dir?

Response: { tenants[], total, page, limit }

GET/v1/tenants/:idAPI key required (enterprise tier)

Single tenant detail plus 30-day usage summary.

Response: { tenant, usage: { totalApiKeys, totalRequests30d, cacheHitRate30d } }; 404 if not found.

B2C Users

Admin-only consumer account management, enterprise tier required.

GET/v1/b2c-usersAPI key required (enterprise tier)

Paginated, searchable, sortable B2C consumer account list.

Request: query: page?, limit? (max 100), q?, sort?, dir?

Response: { users[], total, page, limit }

PATCH/v1/b2c-users/:idAPI key required (enterprise tier)

Grant or revoke the super-admin bypass flag on a user.

Request: { isSuperAdmin: boolean }

Response: The updated user row. 404 if not found.

Branding

GET/v1/branding/:platformKeyNo auth required

Admin-managed branding asset overrides (favicon/app-icon/lockup) for a platform.

Request: params: platformKey ("web"|"portal-horoscope"|"portal-tarot")

Response: { platformKey, assets: Record<assetType, url> }; cached 10 minutes.

Contact

GET/v1/contactNo auth required

The platform's admin-managed public contact identity.

Response: { displayName, contactEmail }; cached 10 minutes.

Webhooks

Unlike every endpoint above (which you call), this is a true webhook: Stripe calls this route. You will never call it directly.

POST/v1/webhooks/stripeStripe webhook signature

Receives and processes inbound Stripe billing events, verified via Stripe's signature scheme.

Request: Raw Stripe event payload; requires a Stripe-Signature header.

Response: 200 { received: true } on success; 400 if the signature is missing or invalid.