API Reference

Base URL: https://cosmicself.ai/api/v1

OpenAPI 3.1 spec available at /openapi.json

Authentication

All API requests require a platform API key in the Authorization header:

bash

curl https://cosmicself.ai/api/v1/capabilities \
  -H "Authorization: Bearer cs_founder_your_key_here"

Get a free Founder key via POST /api/v1/agent-claim or apply at /platform.

Endpoints

POST/api/v1/agent-claimNo auth required

Claim a free Founder API key. First 100 platforms get permanent free access.

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",
    "use_case": "Personalizing AI conversations"
  }'

Example Response (201)

json

{
  "api_key": "cs_founder_abc123def456...",
  "tier": "founder",
  "monthly_credits": 100,
  "overage_rate": 0,
  "expires": "never",
  "message": "Welcome to CosmicSelf. You're Founding Platform #7.",
  "badge_url": "https://cosmicself.ai/badges/founding-platform.svg",
  "next_steps": [
    "Store your api_key — it won't be shown again",
    "Try GET /api/v1/profile?email=you@company.com",
    "Docs: https://cosmicself.ai/docs"
  ]
}

GET/api/v1/profile

Look up a profile by email or platform user ID. Free, unlimited reads.

Query params: email or platform_user_id

bash

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

Example Response

json

{
  "profile_id": "abc-123",
  "status": "ready",
  "generated_at": "2026-03-31T12:00:00Z",
  "user": {
    "name": "Jane",
    "birth_date": "1990-05-15",
    "birth_time": "09:45",
    "birth_location": "Austin, TX"
  },
  "systems": {
    "western": { "sun_sign": "Taurus", "moon_sign": "Aquarius", "rising_sign": "Leo" },
    "vedic": { "moon_nakshatra": "Dhanishta" },
    "human_design": {
      "type": "Generator", "authority": "Sacral",
      "profile": "3/5", "strategy": "To Respond",
      "not_self_theme": "Frustration"
    },
    "numerology": { "life_path": 7, "expression_number": 3, "soul_urge": "9" },
    "cardology": { "birth_card": "7 of Hearts" }
  },
  "traits": {
    "decision_style": "sacral_response",
    "communication_style": "responsive_analytical",
    "motivation_source": "mastery_and_depth",
    "depletion_triggers": ["forced_initiation", "external_pressure_to_rush"],
    "shadow_pattern": "chaos_over_innovation",
    "strength_signals": ["sustainable_life_force_energy", "conceptual_clarity"],
    "cognitive_style": "internalized_framework_builder",
    "rarity_score": 0.04
  },
  "narrative_summary": "A 200-word synthesized summary...",
  "next_steps": [
    "Use traits.decision_style to calibrate how you present options",
    "Use traits.shadow_pattern to proactively name shadow states"
  ]
}

POST/api/v1/profile/generate1 credit

Trigger profile generation for a user. Costs 1 credit. Async (~8 seconds).

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",
    "platform_user_id": "your_user_123"
  }'

Example Response (202)

json

{
  "profile_id": "xyz-789",
  "status": "generating",
  "estimated_seconds": 8,
  "next_steps": [
    "Poll GET /api/v1/profile?email=user@example.com until status is ready",
    "Generation typically completes in 5-10 seconds",
    "This request was billed as 1 profile credit"
  ]
}

GET/api/v1/profile/{id}/traitsFastest

Lightweight traits-only endpoint. Returns just the structured trait object. Use this for real-time agent personalization. Sub-100ms response.

bash

curl "https://cosmicself.ai/api/v1/profile/abc-123/traits" \
  -H "Authorization: Bearer cs_founder_your_key"

GET/api/v1/capabilities

Self-describing endpoint. Returns your API key scopes, credit balance, and rate limits. Designed for agent self-awareness.

bash

curl "https://cosmicself.ai/api/v1/capabilities" \
  -H "Authorization: Bearer cs_founder_your_key"

Example Response

json

{
  "platform_name": "MyAgent",
  "tier": "founder",
  "scopes": ["read", "generate"],
  "credits": {
    "monthly_limit": 100,
    "used": 12,
    "remaining": 88,
    "resets_at": "2026-05-01T00:00:00Z"
  },
  "rate_limit": {
    "requests_per_second": 5
  },
  "next_steps": [
    "GET /api/v1/profile?email=... — Look up a user profile",
    "POST /api/v1/profile/generate — Generate a new profile (1 credit)"
  ]
}

POST/api/v1/notify-operator

Agent escalation endpoint. When a user hasn't generated a profile, this creates a magic link for the operator to send.

bash

curl -X POST "https://cosmicself.ai/api/v1/notify-operator" \
  -H "Authorization: Bearer cs_founder_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_email": "user@example.com",
    "user_name": "Jane",
    "context": "User asked about their decision-making style"
  }'

Trait Object Schema

The traitsobject is the core of the API. Every field is derived from cross-system analysis of the user's birth data.

Field	Type	Description
`decision_style`	string	How the user makes decisions. Values: emotional_authority, sacral_response, splenic_intuition, self_projected, ego_manifested, outer_authority
`communication_style`	string	Preferred communication pattern. E.g. precise_analytical, responsive_expressive, informing_direct
`motivation_source`	string	What drives this person. Values: mastery_and_depth, service_and_connection, vision_and_innovation
`depletion_triggers`	string[]	Patterns that drain this user. E.g. forced_initiation, external_pressure_to_rush, unresolved_mental_loops
`shadow_pattern`	string	The primary shadow behavior pattern derived from their archetype. Format: shadow_over_gift
`strength_signals`	string[]	Natural strengths derived from defined HD centers and Life Path. E.g. consistent_work_capacity, conceptual_clarity
`cognitive_style`	string	How this person processes information. E.g. internalized_framework_builder, open_conceptual_explorer
`rarity_score`	number	Statistical rarity of this profile configuration (0-1, lower = rarer). Score below 0.05 indicates multiple rare configurations.

Error Handling

All errors return a consistent JSON shape with recovery guidance:

json

{
  "error": "rate_limit_exceeded",
  "reason": "Rate limit of 5 req/s exceeded",
  "recoverable": true,
  "requires_human": false,
  "next_steps": [
    "Retry after 1 second(s)",
    "Consider upgrading your tier for higher limits"
  ]
}

Status	Error	Meaning
400	`missing_parameter`	Required query param or body field is missing
401	`unauthorized`	API key is missing, invalid, or inactive
402	`credits_exhausted`	Monthly credit limit reached
403	`insufficient_scope`	API key lacks required permission scope
404	`profile_not_found`	No profile matches the given identifier
410	`founder_cap_reached`	All 100 Founding Platform slots are claimed
429	`rate_limit_exceeded`	Too many requests (check Retry-After header)
500	`internal_error`	Server error (retry is usually safe)
503	`service_unavailable`	Database or dependency unavailable

Rate Limits

Rate limits are enforced per API key using a sliding window algorithm. When rate-limited, the response includes a Retry-After header.

Tier	Requests/sec	Monthly Credits
Founder	5	100 (hard cap)
Starter	10	100
Growth	100	500
Scale	500	2,000
Enterprise	Custom	Custom
Internal	Unlimited	Unlimited

Pricing

Profiles are billed only on first generation (POST /profile/generate). All read requests (GET) are unlimited and free. Profiles are cached permanently.

Founder: Free forever, 100 credits/month, no overage (hard cap)
Starter: $49/mo, 100 credits, $1/overage
Growth: $299/mo, 500 credits, $0.75/overage
Scale: $999/mo, 2,000 credits, $0.60/overage
Enterprise: Custom pricing (contact us)

Claim a free Founder key or apply for a paid tier