AstroCompass
ВурудСабтном

AstroMCP API

Ҳисоби карта, гороскопҳо, таро ва идоракунии ҳисоб, ҳама ҳамчун REST API. Ин маълумотнома ҳамаи нуқтаҳои охири APIи AstroMCP-ро ҳуҷҷатгузорӣ мекунад.

astromcp.com ҳанӯз фаъол нест; шумо инро дар маркази AstroCompass мехонед. URL-ҳои асосӣ ва ҷараёни калиди худхидматрасонӣ пас аз роҳандозии ин домен ба ин ҷо кӯчонида мешаванд.

Тасдиқи ҳувият

Ҳар нуқтаи охир ба ғайр аз онҳое ки «Тасдиқи ҳувият лозим нест» нишон дода шудааст, калиди API-и шуморо ҳамчун токени bearer интизор аст:

Authorization: Bearer <your-api-key>

Ҳар посухи хатогӣ, аз ҳар нуқтаи охир, як шакли муштарак дорад:

{
  "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.