AstroMCP API

Cálculo de cartas, horóscopos, tarot y gestión de cuentas, todo como API REST. Esta referencia documenta todos los endpoints que expone actualmente la AstroMCP API.

astromcp.com aún no está activo; estás leyendo esto en el hub de AstroCompass. Las URLs base y el flujo de claves de autoservicio se trasladarán aquí una vez que ese dominio esté desplegado.

Autenticación

Todos los endpoints siguientes, excepto los marcados como "Sin autenticación requerida", esperan tu clave API como token de portador:

Authorization: Bearer <your-api-key>

Todas las respuestas de error, de cualquier endpoint, comparten la misma estructura:

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