Cosmo AI Agent API

Chat with Cosmo, your AI astrology advisor, using Server-Sent Events (SSE) for real-time streaming 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 SSE 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 Server-Sent Events (SSE) stream for real-time responses.

Response Headers

The following custom headers are included in the response:

SSE Stream Format

data: {"type":"text-delta","textDelta":"Hello"}

data: {"type":"text-delta","textDelta":", how"}

data: {"type":"text-delta","textDelta":" can I"}

data: {"type":"finish","finishReason":"stop"}

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 SSE
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 SSE stream
const reader = response.body?.getReader();
const decoder = new TextDecoder();

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

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      console.log(data);
    }
  }
}

Python

import requests
import json

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)

for line in response.iter_lines():
    if line:
        line = line.decode('utf-8')
        if line.startswith('data: '):
            event_data = json.loads(line[6:])
            print(event_data)

---

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 SSE properly: Implement proper SSE 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)