API Documentation

Complete reference for the Horoscope Today API. Get personalized daily forecasts based on natal chart calculations.

Base URL: https://zodiac-today.com JSON responses

Authentication

All API endpoints (except auth) require an API key. Include it in the Authorization header:

Authorization: Bearer hsk_your_api_key

Your API key is generated automatically on first login. You can manage keys from the Dashboard.

Auth Endpoints

POST /api/auth/send-code No auth required

Send a 6-digit verification code to an email address. Creates a new user if the email is not registered.

Request Body
{ "email": "user@example.com" }
Response 200
{ "message": "Verification code sent" }
POST /api/auth/verify No auth required

Verify the 6-digit code. Returns user info and sets a session cookie. Auto-generates an API key on first login.

Request Body
{ "email": "user@example.com", "code": "123456" }
Response 200
{ "id": "clxyz...", "email": "user@example.com", "tier": "free", "apiKey": "hsk_abc123..." }
GET /api/auth/me API Key

Get the current user's info, profile count, and tier limits.

Response 200
{ "id": "clxyz...", "email": "user@example.com", "tier": "free", "profileCount": 1, "maxProfiles": 1, "maxDaysFromToday": 1 }

Profile Endpoints

GET /api/profiles API Key

List all profiles belonging to the authenticated user.

Response 200
{ "profiles": [ { "id": "clxyz...", "name": "John", "birthDate": "1990-05-15", "birthCity": "London, UK", "sunSign": "Taurus", "createdAt": "2026-02-09T..." } ] }
POST /api/profiles API Key

Create a new profile. The birth city is geocoded to coordinates automatically. Sun sign is calculated from the birth date.

Request Body
{ "name": "John", "birthDate": "1990-05-15", "birthCity": "London, UK" }
Response 201
{ "id": "clxyz...", "name": "John", "birthDate": "1990-05-15", "birthCity": "London, England, United Kingdom", "latitude": 51.5073219, "longitude": -0.1276474, "sunSign": "Taurus" }
DELETE /api/profiles/:id API Key

Delete a profile and all its cached horoscopes. Only the profile owner can delete it.

Horoscope Endpoint

GET /api/horoscope/daily API Key

Get personalized daily horoscope forecasts for a profile. Calculates planetary transit aspects against the natal chart to determine favorable/unfavorable activities, overall rating, and metrics.

Query Parameters
Parameter Type Description
profileId string Required. The profile ID to generate horoscopes for.
startDate YYYY-MM-DD Required. Start of the date range.
endDate YYYY-MM-DD Required. End of the date range (max based on tier).
Tier Limits
Tier Max Profiles Max Days from Today
Free11 (today + tomorrow)
Starter ($4.99/mo)330
Pro ($9.99/mo)590
Premium ($19.99/mo)10365
Response 200
{
  "profileId": "clxyz...",
  "profileName": "John",
  "sunSign": "Taurus",
  "horoscopes": [
    {
      "date": "2026-02-09",
      "overallRating": 7.8,
      "metrics": {
        "energy": "High",
        "focus": "Moderate",
        "romance": "Good",
        "luck": "High"
      },
      "favorable": [
        "Job interviews",
        "Starting a fitness routine",
        "Weekend trips"
      ],
      "unfavorable": [
        "Major purchases",
        "Confrontations"
      ],
      "luckyColors": [
        { "name": "Rose Pink", "hex": "#FF007F" },
        { "name": "Royal Purple", "hex": "#7851A9" },
        { "name": "Forest Green", "hex": "#228B22" }
      ],
      "luckyNumbers": [7, 23, 42, 68],
      "summary": "With transit Venus forming a trine to your natal Sun..."
    }
  ]
}
Error Responses
401 Not authenticated
400 Missing or invalid parameters
403 Date range exceeds tier limit
404 Profile not found or not owned by user

Interactive API Tester

Sign in to test the API with your profiles.

Sign In

cURL Examples

Create a profile

curl -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"}'

Get daily horoscope

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

List profiles

curl https://zodiac-today.com/api/profiles \
  -H "Authorization: Bearer hsk_your_api_key"

Get current user info

curl https://zodiac-today.com/api/auth/me \
  -H "Authorization: Bearer hsk_your_api_key"