Quickstart

Add cosmic identity personalization to your AI agent in 5 minutes. No credit card required.

1

Claim your Founder key

POST to /api/v1/agent-claim with your agent name, creator email, and platform URL. First 100 platforms get permanent free access — 100 profile credits per month, forever.

bash
curl -X POST "https://cosmicself.ai/api/v1/agent-claim" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "MyAgent",
    "creator_email": "you@company.com",
    "platform_url": "https://your-app.com"
  }'

Save the api_keyfrom the response — it's shown only once.

2

Install and configure

Store your API key securely. Set the base URL to https://cosmicself.ai/api/v1. All requests use the Authorization header.

environment variable
COSMICSELF_API_KEY=cs_founder_your_key_here
COSMICSELF_BASE_URL=https://cosmicself.ai/api/v1
3

Generate a profile

POST birth data to generate a full cosmic identity profile. This costs 1 credit and takes ~8 seconds. The profile is cached permanently after first generation.

bash
curl -X POST "https://cosmicself.ai/api/v1/profile/generate" \
  -H "Authorization: Bearer cs_founder_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "name": "Jane",
    "birth_date": "1990-05-15",
    "birth_time": "09:45",
    "birth_location": "Austin, TX"
  }'
4

Fetch the profile

Once generation is complete, fetch the full profile with GET /profile. For real-time use, the /traits endpoint returns just the structured trait object in under 100ms.

bash
# Full profile
curl "https://cosmicself.ai/api/v1/profile?email=user@example.com" \
  -H "Authorization: Bearer cs_founder_your_key"

# Traits only (fastest)
curl "https://cosmicself.ai/api/v1/profile/PROFILE_ID/traits" \
  -H "Authorization: Bearer cs_founder_your_key"
5

Inject traits into your agent

Use the returned traits to personalize your AI agent's system prompt. The trait fields map directly to actionable personalization dimensions.

system prompt snippet
You have access to this user's cosmic identity profile. Use it to personalize:
- Decision style: {{traits.decision_style}} — calibrate how you present options
- Communication style: {{traits.communication_style}} — match your tone and depth
- Shadow pattern: {{traits.shadow_pattern}} — name it gently when you see it
- Strength signals: {{traits.strength_signals}} — reflect these back to reinforce
- HD Strategy: {{systems.human_design.strategy}} — timing and pacing guidance
Do not explain the systems unprompted. Just use the data.

What's next?