Personality / Emotions API for Agents powered by Astrology
LLM integration reference
Version: v1

Base URL
- Production API base is deployment-specific.
- This frontend is currently configured for:
  https://cs-be-prod2.up.railway.app

Auth model
1) Account session token (for account management endpoints)
   - Obtain via POST /api/agents/signup or POST /api/agents/login
   - Send as header:
     Authorization: Bearer <accessToken>
2) Runtime API key (for runtime personality endpoint)
   - Issued at signup and key regeneration.
   - Send as header:
     x-agent-api-key: <csa_...>

Commercial access
- No trial tier.
- Runtime snapshot endpoint requires active paid subscription.
- If not active, API returns HTTP 402.

Core endpoints
- POST /api/agents/signup
  Creates agent account, natal chart, access token, and one-time runtime API key.
- POST /api/agents/login
  Signs into existing account and returns access token.
- GET /api/agents/me
  Returns account profile, plan status, subscription status, chart summary.
- POST /api/agents/birth-chart
  Updates natal data (auto by generation or manual coordinates/timezone).
- POST /api/agents/regenerate-api-key
  Rotates runtime key and returns one-time visible key.
- POST /api/agents/checkout-session
  Returns Stripe checkout URL for paid activation.
- POST /api/agents/portal-session
  Returns Stripe billing portal URL.
- POST /api/agents/personality-snapshot
  Returns deterministic score vector for runtime behavior.

Runtime snapshot response shape (example)
{
  "success": true,
  "data": {
    "agentId": "agt_xxx",
    "planStatus": "active",
    "subscriptionStatus": "active",
    "snapshot": {
      "scoreVector": {
        "focus": 71,
        "social": 48,
        "risk": 36,
        "stability": 82,
        "mood": 63
      }
    }
  }
}

Runtime curl example
curl -X POST https://cs-be-prod2.up.railway.app/api/agents/personality-snapshot \
  -H 'x-agent-api-key: csa_your_key' \
  -H 'Content-Type: application/json' \
  -d '{}'

Error semantics
- 400 bad request: invalid payload
- 401 unauthorized: missing/invalid token or API key
- 402 payment required: active subscription required
- 404 not found: account/resource missing
- 500 server error: transient backend failure

Notes for LLM/agent implementers
- Treat scores as deterministic state inputs, not natural language directives.
- Cache snapshot per decision window to reduce repeated calls.
- Keep runtime key secret; never expose full key in client-visible logs.