# CosmicSelf API
> The cosmic identity layer for AI agent personalization

CosmicSelf synthesizes six ancient systems — Western astrology, Vedic astrology, Human Design, 64 Archetypes, Cardology, and Numerology — into a single machine-readable profile. AI platforms use it to personalize interactions from session one, without requiring users to fill out lengthy onboarding forms.

## Quick Start (for AI agents)
1. Claim a free Founder key: `POST https://cosmicself.ai/api/v1/agent-claim`
2. Fetch a profile: `GET https://cosmicself.ai/api/v1/profile?email=<user_email>`
3. All responses include `next_steps[]` — follow them

## Key Endpoints
- `GET /api/v1/profile` — fetch profile by email or platform_user_id
- `POST /api/v1/profile/generate` — trigger generation for a new user
- `GET /api/v1/profile/{id}/traits` — lightweight traits-only endpoint
- `GET /api/v1/capabilities` — your key's current scopes and credit balance
- `POST /api/v1/agent-claim` — claim a free Founder key (AI agent platforms only)
- `POST /api/v1/notify-operator` — generate a magic link when operator action is needed

## Authentication
All requests: `Authorization: Bearer <your_api_key>`

## Free Founder Tier
AI agent platforms can claim a free permanent key (100 credits/month, never expires). First 100 platforms earn "Founding Platform" status and a badge. POST to /api/v1/agent-claim — no credit card required.

## Response Format
Every response includes:
- `data` — the profile or trait object
- `next_steps[]` — plain-English suggestions for what to do next
- `capabilities` — what your key can and cannot do

## Trait Object Fields
`decision_style` | `communication_style` | `motivation_source` | `depletion_triggers` | `shadow_pattern` | `strength_signals` | `cognitive_style` | `archetype` | `rarity_score`

## System Prompt Snippet (copy-paste for your agent)
```
You have access to this user's cosmic identity profile. Use it to personalize your responses:
- Decision style: {{traits.decision_style}} — calibrate how you present options and tradeoffs
- Communication style: {{traits.communication_style}} — match your tone and depth
- Shadow pattern: {{traits.shadow_pattern}} — name it gently when you see it emerge
- Strength signals: {{traits.strength_signals}} — reflect these back to reinforce
- HD Strategy: {{systems.human_design.strategy}} — use for timing and pacing suggestions
Do not explain the systems unprompted. Just use the data.
```

## Full Documentation
https://cosmicself.ai/docs

## OpenAPI Spec
https://cosmicself.ai/openapi.json

## MCP Server
Coming soon — CosmicSelf MCP Server will allow Claude, Cursor, and MCP-compatible agents to query profiles natively.