{
  "openapi": "3.1.0",
  "info": {
    "title": "CosmicSelf API",
    "version": "1.0.0",
    "description": "Cosmic identity API for AI agent personalization. Six ancient systems — Western astrology, Vedic, Human Design, 64 Archetypes, Cardology, Numerology — synthesized into machine-readable profiles.",
    "contact": {
      "name": "CosmicSelf API Support",
      "email": "api@cosmicself.ai",
      "url": "https://cosmicself.ai/docs"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://cosmicself.ai/api/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/profile": {
      "get": {
        "operationId": "getProfile",
        "summary": "Look up a profile by email or platform user ID",
        "description": "Returns the full cosmic identity profile including all six systems and synthesized traits. Read requests are free and unlimited.",
        "parameters": [
          {
            "name": "email",
            "in": "query",
            "description": "User email address",
            "schema": { "type": "string", "format": "email" }
          },
          {
            "name": "platform_user_id",
            "in": "query",
            "description": "Your platform's internal user ID",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Profile found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProfileResponse" }
              }
            }
          },
          "404": {
            "description": "Profile not found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        },
        "x-cosmicself-next-steps": [
          "Use traits.decision_style to calibrate how you present options",
          "Use traits.shadow_pattern to proactively name shadow states"
        ]
      }
    },
    "/profile/generate": {
      "post": {
        "operationId": "generateProfile",
        "summary": "Generate a cosmic identity profile for a new user",
        "description": "Triggers profile generation. Costs 1 credit. Runs async (~8 seconds). Poll GET /profile until status is 'ready'.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/GenerateRequest" },
              "example": {
                "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"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Generation started",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GenerateResponse" }
              }
            }
          },
          "402": {
            "description": "Credits exhausted",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/profile/{id}/traits": {
      "get": {
        "operationId": "getTraits",
        "summary": "Get traits-only (lightweight)",
        "description": "Returns just the structured trait object. Use this for real-time agent personalization where speed matters. Sub-100ms response.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Profile ID",
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": {
            "description": "Traits returned",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TraitsResponse" }
              }
            }
          }
        }
      }
    },
    "/capabilities": {
      "get": {
        "operationId": "getCapabilities",
        "summary": "Self-describing endpoint for agent self-awareness",
        "description": "Returns your API key's scopes, credit balance, and rate limits. Designed for AI agents to understand what they can do.",
        "responses": {
          "200": {
            "description": "Capabilities returned",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CapabilitiesResponse" },
                "example": {
                  "platform_name": "my-agent",
                  "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)"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/notify-operator": {
      "post": {
        "operationId": "notifyOperator",
        "summary": "Agent escalation — request operator action",
        "description": "When a user hasn't generated a profile, creates a magic link the operator can send to the user.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["user_email"],
                "properties": {
                  "user_email": { "type": "string", "format": "email" },
                  "user_name": { "type": "string" },
                  "context": { "type": "string", "description": "Why the agent needs the profile" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Magic link generated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "magic_link": { "type": "string", "format": "uri" },
                    "next_steps": { "type": "array", "items": { "type": "string" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/agent-claim": {
      "post": {
        "operationId": "claimFounderKey",
        "summary": "Claim a free Founder API key (AI agent platforms)",
        "description": "AI agent platforms can claim a free permanent key. 100 credits/month, never expires. First 100 platforms get Founding Platform badge. No credit card required.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AgentClaimRequest" },
              "example": {
                "agent_name": "Homer",
                "creator_email": "todd@spontent.com",
                "platform_url": "https://heyhomer.com",
                "use_case": "Personalizing morning briefings based on HD type and archetype"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Founder key issued",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentClaimResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limited (1 claim per email per 24h)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Platform API key. Get one at https://cosmicself.ai/platform or POST /api/v1/agent-claim"
      }
    },
    "schemas": {
      "TraitObject": {
        "type": "object",
        "properties": {
          "decision_style": { "type": "string" },
          "communication_style": { "type": "string" },
          "motivation_source": { "type": "string" },
          "depletion_triggers": { "type": "array", "items": { "type": "string" } },
          "shadow_pattern": { "type": "string" },
          "strength_signals": { "type": "array", "items": { "type": "string" } },
          "cognitive_style": { "type": "string" },
          "rarity_score": { "type": "number", "minimum": 0, "maximum": 1 }
        }
      },
      "ProfileResponse": {
        "type": "object",
        "properties": {
          "profile_id": { "type": "string", "format": "uuid" },
          "status": { "type": "string", "enum": ["ready", "generating", "failed"] },
          "generated_at": { "type": "string", "format": "date-time" },
          "user": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "birth_date": { "type": "string" },
              "birth_time": { "type": "string" },
              "birth_location": { "type": "string" }
            }
          },
          "systems": { "type": "object" },
          "traits": { "$ref": "#/components/schemas/TraitObject" },
          "narrative_summary": { "type": "string" },
          "next_steps": { "type": "array", "items": { "type": "string" } }
        }
      },
      "GenerateRequest": {
        "type": "object",
        "required": ["email", "name", "birth_date", "birth_time", "birth_location"],
        "properties": {
          "email": { "type": "string", "format": "email" },
          "name": { "type": "string" },
          "birth_date": { "type": "string", "description": "YYYY-MM-DD format" },
          "birth_time": { "type": "string", "description": "HH:MM format (24h)" },
          "birth_location": { "type": "string", "description": "City, State/Country" },
          "platform_user_id": { "type": "string" }
        }
      },
      "GenerateResponse": {
        "type": "object",
        "properties": {
          "profile_id": { "type": "string", "format": "uuid" },
          "status": { "type": "string", "enum": ["generating"] },
          "estimated_seconds": { "type": "integer" },
          "next_steps": { "type": "array", "items": { "type": "string" } }
        }
      },
      "TraitsResponse": {
        "type": "object",
        "properties": {
          "profile_id": { "type": "string", "format": "uuid" },
          "traits": { "$ref": "#/components/schemas/TraitObject" },
          "next_steps": { "type": "array", "items": { "type": "string" } }
        }
      },
      "CapabilitiesResponse": {
        "type": "object",
        "properties": {
          "platform_name": { "type": "string" },
          "tier": { "type": "string", "enum": ["founder", "starter", "growth", "scale", "enterprise", "internal"] },
          "scopes": { "type": "array", "items": { "type": "string" } },
          "credits": {
            "type": "object",
            "properties": {
              "monthly_limit": { "type": "integer" },
              "used": { "type": "integer" },
              "remaining": { "type": "integer" },
              "resets_at": { "type": "string", "format": "date-time" }
            }
          },
          "rate_limit": {
            "type": "object",
            "properties": {
              "requests_per_second": { "type": "integer" }
            }
          },
          "next_steps": { "type": "array", "items": { "type": "string" } }
        }
      },
      "AgentClaimRequest": {
        "type": "object",
        "required": ["agent_name", "creator_email", "platform_url"],
        "properties": {
          "agent_name": { "type": "string", "description": "Your AI agent's name" },
          "creator_email": { "type": "string", "format": "email" },
          "platform_url": { "type": "string", "format": "uri" },
          "use_case": { "type": "string", "description": "How you'll use cosmic identity data" }
        }
      },
      "AgentClaimResponse": {
        "type": "object",
        "properties": {
          "api_key": { "type": "string", "description": "Your API key (shown once)" },
          "tier": { "type": "string", "enum": ["founder"] },
          "monthly_credits": { "type": "integer" },
          "overage_rate": { "type": "integer" },
          "expires": { "type": "string" },
          "message": { "type": "string" },
          "badge_url": { "type": "string", "format": "uri" },
          "next_steps": { "type": "array", "items": { "type": "string" } }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "reason": { "type": "string" },
          "recoverable": { "type": "boolean" },
          "requires_human": { "type": "boolean" },
          "next_steps": { "type": "array", "items": { "type": "string" } }
        }
      }
    }
  }
}