Cosmo AI Agent API

Chat with Cosmo, your AI astrology advisor, using text streaming for real-time responses.

Base Cost: 5-10 credits (model dependent) + token usage

Perfect for integrating AI astrological guidance into your applications.

---

Chat with Cosmo

Start or continue a conversation with Cosmo using text streaming.

Endpoint

POST /api/v1/cosmo/chat

Pricing

Credits are consumed based on model tier and usage:

Credits are deducted after response generation based on actual token usage.

Request Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Alternative: You can also use X-API-Key header instead of Authorization:

X-API-Key: YOUR_API_KEY
Content-Type: application/json

Request Body

{
  "messages": [
    {
      "role": "user",
      "content": "What transits are affecting me today?"
    }
  ],
  "conversationId": "optional-conversation-id",
  "model": "standard"
}

Parameters

Message Object

Response Format

The API returns a plain text stream for real-time responses.

Response Headers

The following custom headers are included in the response:

Stream Format

The response streams plain text chunks directly:

Hey! I'm Cosmo, your practical life advisor.

I'm here to help with real stuff — work decisions, relationship questions...

Each chunk is delivered as soon as it's generated, enabling real-time display in your application.

Status Codes

Error Response

{
  "error": "Insufficient credits",
  "message": "This request requires approximately 15 credits, but you only have 5 available",
  "required": 15,
  "available": 5
}

---

Example Requests

cURL

curl -X POST https://mycosmicadvisor.com/api/v1/cosmo/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What transits are affecting me today?"
      }
    ],
    "model": "standard"
  }'

JavaScript / TypeScript

// Using fetch with streaming
const response = await fetch('https://mycosmicadvisor.com/api/v1/cosmo/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messages: [
      { role: 'user', content: 'Tell me about my Venus placement' }
    ],
    model: 'standard',
  }),
});

// Read custom headers
const conversationId = response.headers.get('X-Conversation-Id');
const estimatedCost = response.headers.get('X-Estimated-Cost');

// Read text stream
const reader = response.body?.getReader();
const decoder = new TextDecoder();
let fullResponse = '';

while (true) {
  const { done, value } = await reader!.read();
  if (done) break;

  const chunk = decoder.decode(value, { stream: true });
  fullResponse += chunk;

  // Display chunk in real-time
  process.stdout.write(chunk);
}

console.log('\nComplete response:', fullResponse);

Python

import requests

url = "https://mycosmicadvisor.com/api/v1/cosmo/chat"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "messages": [
        {"role": "user", "content": "What can you tell me about my Moon sign?"}
    ],
    "model": "standard"
}

# Streaming response
response = requests.post(url, headers=headers, json=data, stream=True)

# Read custom headers
conversation_id = response.headers.get('X-Conversation-Id')
estimated_cost = response.headers.get('X-Estimated-Cost')

# Read text stream
full_response = ""
for chunk in response.iter_content(chunk_size=None, decode_unicode=True):
    if chunk:
        full_response += chunk
        print(chunk, end='', flush=True)

print(f"\n\nConversation ID: {conversation_id}")
print(f"Estimated Cost: {estimated_cost} credits")

---

Multi-turn Conversations

To maintain conversation context, use the same conversationId across requests:

// First message
const conversationId = crypto.randomUUID();

await fetch('https://mycosmicadvisor.com/api/v1/cosmo/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    conversationId,
    messages: [
      { role: 'user', content: 'Tell me about my Sun sign' }
    ],
  }),
});

// Follow-up message (uses same conversationId)
await fetch('https://mycosmicadvisor.com/api/v1/cosmo/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    conversationId, // Same ID
    messages: [
      { role: 'user', content: 'Tell me about my Sun sign' },
      { role: 'assistant', content: '...' }, // Previous response
      { role: 'user', content: 'How does it affect my relationships?' }
    ],
  }),
});

---

Requirements

To use the Cosmo API, you need:

1. Credits in your account (personal or organization)

Using Cosmo With and Without Blueprints

With Blueprint (Recommended)

When you have a blueprint created:

• Get personalized astrological insights based on your birth chart
• Receive guidance tailored to your specific placements and aspects
• Access transit interpretations for your unique chart
• Get relationship compatibility analysis with other blueprints

Example questions:

• "What transits are affecting me this week?"
• "How does my Venus placement influence my relationships?"
• "What's my career path based on my 10th house?"

Without Blueprint (General Mode)

Without a blueprint, Cosmo can still help with:

• General astrological knowledge and concepts
• Current planetary transits (not personalized)
• Astrological timing for decisions
• General guidance on zodiac signs and houses

Example questions:

• "What does Mercury retrograde mean?"
• "What are the current planetary transits?"
• "When is a good time to start a new project?"
• "What does it mean to have Venus in the 7th house?"

Tip: Create a blueprint to get the most value from Cosmo!

---

Rate Limits

Rate limits are applied per API key:

When rate limited, you'll receive a 429 Too Many Requests response with headers:

• X-RateLimit-Limit: Request limit
• X-RateLimit-Remaining: Remaining requests
• X-RateLimit-Reset: Time when limit resets (Unix timestamp)

---

Organization API Keys

When using an organization API key:

• Credits are deducted from the organization's balance
• Cosmo accesses organization blueprints instead of personal blueprints
• Usage is logged under the organization
• Admin or Owner role required to create organization API keys

To use an organization API key, simply use it in the Authorization header. The system automatically detects organization context.

---

Best Practices

1. Reuse conversation IDs: For multi-turn conversations, maintain the same conversationId
2. Handle streaming properly: Implement proper text stream parsing and error handling
3. Monitor credits: Check credit balance before making requests
4. Use standard model for simple queries: Reserve premium for complex analysis
5. Implement retry logic: Handle rate limits with exponential backoff
6. Secure your API key: Never expose it in client-side code

---

Model Tiers

Choose the model tier based on your needs by passing the model parameter in your request body.

Cosmo Standard (model: "standard")

• Best for: Quick questions, general guidance, daily use
• Speed: Fast responses
• Cost: 5 credits base + 1 credit per message
• Example use cases: "How's my week?", "What's Mercury retrograde?", "When should I have this conversation?"

Cosmo Premium (model: "premium")

• Best for: Deep analysis, complex questions, multi-blueprint comparisons
• Speed: Slightly slower but more thorough
• Cost: 10 credits base + 2 credits per message
• Example use cases: "Analyze my career path in depth", "Compare my chart with my partner's", "Detailed transit analysis for next month"

Note:

• If no model parameter is provided, defaults to standard
• Model tiers may be updated to use newer AI models without changing the API interface
• Pricing remains consistent regardless of underlying model changes
• Credits are always deducted from your pay-as-you-go balance (personal or organization)

---

White Label Customization

NEW: Customize the Cosmo agent with your own branding and personality while keeping access to all astrology tools.

Agent Configuration

Add an optional agent object to your request body to customize the AI personality:

{
  "messages": [...],
  "model": "standard",
  "agent": {
    "name": "Luna",
    "tone": "mystical, empathetic, and intuitive",
    "language": "en",
    "customInstructions": "Always acknowledge divine timing. Mention moon phases when relevant.",
    "prohibitedTopics": ["politics"],
    "responseStyle": "detailed"
  }
}

Agent Parameters

White Label Examples

Mystical/Spiritual App

curl -X POST https://mycosmicadvisor.com/api/v1/cosmo/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "What energy should I expect?"}],
    "agent": {
      "name": "Luna",
      "tone": "mystical, empathetic, and intuitive",
      "language": "en",
      "responseStyle": "detailed"
    }
  }'

Professional/Career App

curl -X POST https://mycosmicadvisor.com/api/v1/cosmo/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Best time for a meeting?"}],
    "agent": {
      "name": "Stellar",
      "tone": "professional, strategic, and direct",
      "customInstructions": "Focus on career timing and business opportunities.",
      "responseStyle": "short"
    }
  }'

Relationship/Love App

curl -X POST https://mycosmicadvisor.com/api/v1/cosmo/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Are we compatible?"}],
    "agent": {
      "name": "Venus",
      "tone": "romantic, compassionate, and insightful",
      "customInstructions": "Prioritize relationship dynamics and emotional growth.",
      "prohibitedTopics": ["politics"]
    }
  }'

White Label Security

• Protected Instructions: Cannot override core tool usage or timing rules
• Validation: All fields validated server-side with clear error messages
• No Extra Cost: White label included at no additional charge
• Backward Compatible: Existing API calls work without changes

📚 Full White Label Guide: /api-docs/white-label