Zodiac Horoscope

Provide personalized, actionable daily guidance powered by planetary transit calculations against the user's natal chart.

Required Environment Variables

Variable	Description
ZODIAC_API_KEY	API key from zodiac-today.com (starts with hsk_)
ZODIAC_PROFILE_ID	Profile ID for the user's birth chart

Privacy Notice

This skill collects sensitive PII (email, birth date, birth city) required for natal chart calculations. Handle with care:

• Ask for explicit user consent before collecting birth information
• Never log or expose PII in public channels or shared contexts
• Store API keys and profile IDs in environment variables, not in plain text files
• Delete cookies.txt after registration is complete

How This Helps People

• Daily decision-making: "Should I have that difficult conversation today?" → Check if confrontations are favorable or unfavorable
• Schedule optimization: Plan high-energy tasks on high-energy days, rest on low days
• Life event planning: Find the best window for job interviews, first dates, travel, or big purchases (paid tiers unlock future dates)
• Relationship insights: Romance metrics help users pick ideal date nights
• Motivation & mindfulness: Daily summaries provide a moment of reflection and intentional living

Setup

Everything can be done via API — no browser needed.

1. Register & get API key

# Send verification code (creates account if new)
curl -s -X POST https://zodiac-today.com/api/auth/send-code \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'

# Verify code (check email inbox for 6-digit code)
curl -s -X POST https://zodiac-today.com/api/auth/verify \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"user@example.com","code":"123456"}'

# Create API key (use session cookie from verify step)
curl -s -X POST https://zodiac-today.com/api/keys \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"name":"My Agent"}'
# Response: {"id":"...","key":"hsk_...","name":"My Agent"}

Store the hsk_ key as environment variable ZODIAC_API_KEY. Delete cookies.txt after this step.

2. Create birth profile

curl -s -X POST https://zodiac-today.com/api/profiles \
  -H "Authorization: Bearer hsk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"John","birthDate":"1990-05-15","birthCity":"London, UK"}'

Save the returned id as environment variable ZODIAC_PROFILE_ID.

Workflow

First-time setup for a user

1. Ask for their email, birth date, and birth city (get explicit consent — this is sensitive PII)
2. Send verification code: POST /api/auth/send-code with their email
3. Human-in-the-loop: Ask the user to check their email and provide the 6-digit code. If the agent has email access (e.g., IMAP), it may retrieve the code automatically from noreply@zodiac-today.com
4. Verify code: POST /api/auth/verify — save session cookie to a temp file (-c cookies.txt)
5. Create API key: POST /api/keys (with session cookie) — save the returned hsk_ key
6. Clean up: Delete cookies.txt immediately — it is no longer needed
7. Create profile: POST /api/profiles (with API key) — save the returned profile id
8. Store ZODIAC_API_KEY and ZODIAC_PROFILE_ID as environment variables

Daily horoscope fetch

1. Call GET /api/horoscope/daily?profileId=$ZODIAC_PROFILE_ID&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD with Authorization: Bearer $ZODIAC_API_KEY
2. Parse the response and present actionable insights

Presenting results to users

Translate raw data into practical advice:

• overallRating (1-10): Frame as "Great day!" (8+), "Solid day" (6-8), "Take it easy" (<6)
• favorable/unfavorable: Present as "Good for:" and "Better to avoid:" lists
• metrics: Highlight the standout ones — "Your energy is HIGH today, perfect for tackling that project"
• luckyColors: Suggest outfit or decor choices
• luckyNumbers: Mention casually, fun touch
• summary: Use the astrological narrative to add color, but keep advice grounded and practical

Planning ahead (paid tiers)

For users with Starter+ tiers, fetch date ranges to help:

• "What's the best day this month for my job interview?"
• "When should I plan our anniversary dinner?"
• Compare overallRating across dates and recommend the highest-rated windows

API Details

See references/api.md for full endpoint docs, parameters, tiers, and response schemas.

Example curl

curl "https://zodiac-today.com/api/horoscope/daily?profileId=PROFILE_ID&startDate=2026-02-15&endDate=2026-02-15" \
  -H "Authorization: Bearer hsk_your_api_key"