API Reference

Comprehensive documentation for the Chaos Tarot REST API. All endpoints use JSON request/response bodies unless otherwise noted. The base URL is https://chaos-tarot.com

Authentication

Chaos Tarot uses a passwordless access code system. When a user registers with their email, they receive a unique access code (format: XXXX-XXXX-XXXX) that acts as both their identifier and authentication credential.

For GET requests, pass the access code as a code query parameter. For POST requests, include it in the JSON body as accessCode.

Access Tiers

Free — 1 draw per system per day, basic stats, no AI interpretation
Initiate ($7.77 one-time) — All spreads, full collection tracker, all divination items
Oracle ($5.55/mo) — AI interpretation, Memory Core, follow-up questions, journal, AI summarize

Admin endpoints require an access code with admin privileges. Cron endpoints require a Bearer token matching the CRON_SECRET environment variable.

Rate Limits

All API endpoints are rate-limited per IP address using a sliding window. When a rate limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Endpoint Group	Limit	Window
Registration	5 requests	1 minute
Auth validation	20 requests	1 minute
AI interpretation / follow-up / summarize	10 requests	1 minute
Daily draws (all systems)	20 requests	1 minute
Readings (save/list/export)	30 requests	1 minute
Error telemetry	30 requests	1 minute

Authentication

Register for access codes and validate credentials. Chaos Tarot uses a passwordless access-code system rather than traditional username/password.

POST/api/auth/register-freePublic5 per minute per IP

Parameters

Name	Type	Required	Description
email	string	required	User email address

Response

{ "accessCode": "XXXX-XXXX-XXXX", "tier": "free" }

Example

curl -X POST https://chaos-tarot.com/api/auth/register-free \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

POST/api/auth/validatePublic20 per minute per IP

Validate an access code and return the user's tier information.

Parameters

Name	Type	Required	Description
accessCode	string	required	The user's access code

Response

{ "valid": true, "tier": "oracle", "isAdmin": false }

Example

curl -X POST https://chaos-tarot.com/api/auth/validate \
  -H "Content-Type: application/json" \
  -d '{"accessCode": "XXXX-XXXX-XXXX"}'

GET/api/auth/statusAccess Code

Check authentication status for the current access code.

Parameters

Name	Type	Required	Description
code	string (query)	required	Access code

Response

{ "authenticated": true, "tier": "initiate", "email": "user@example.com" }

Readings

Save, list, export, and manage divination readings across all eight systems.

POST/api/readings/saveAccess Code30 per minute per IP

Save a completed reading (cards drawn, positions, interpretation) to the user's history.

Parameters

Name	Type	Required	Description
accessCode	string	required	User access code
systemId	string	required	Divination system ID (e.g. "chaos-tarot", "elder-futhark")
spreadType	string	required	Spread type slug
cards	Card[]	required	Array of drawn cards with position data
interpretation	string	optional	AI or manual interpretation text
question	string	optional	The question the user asked

Response

{ "id": "uuid", "createdAt": "2026-03-01T12:00:00Z" }

GET/api/readings/listAccess Code

List saved readings for a user, with pagination and optional system filter.

Parameters

Name	Type	Required	Description
code	string (query)	required	Access code
page	number (query)	optional	Page number (default: 1)
limit	number (query)	optional	Results per page (default: 20, max: 50)
system	string (query)	optional	Filter by system ID

Response

{ "readings": [...], "total": 42, "page": 1, "totalPages": 3 }

GET/api/readings/exportAccess Code

Export all readings as JSON for data portability.

Parameters

Name	Type	Required	Description
code	string (query)	required	Access code

Response

{ "readings": [...], "exportedAt": "2026-03-01T12:00:00Z" }

POST/api/readings/favoriteAccess Code

Toggle the favorite status of a reading.

Parameters

Name	Type	Required	Description
accessCode	string	required	Access code
readingId	string	required	Reading UUID

Response

{ "favorited": true }

POST/api/readings/reflectAccess Code

Add a personal reflection/journal note to a saved reading.

Parameters

Name	Type	Required	Description
accessCode	string	required	Access code
readingId	string	required	Reading UUID
reflection	string	required	Reflection text

Response

{ "success": true }

GET/api/readings/check-limitAccess Code

Check whether the user has remaining free reads for a system today.

Parameters

Name	Type	Required	Description
code	string (query)	required	Access code
system	string (query)	required	System ID

Response

{ "allowed": true, "remaining": 1 }

GET/api/readings/sharedPublic

Retrieve a publicly shared reading by its share token.

Parameters

Name	Type	Required	Description
token	string (query)	required	Share token

Response

{ "reading": { ... }, "sharedBy": "Anonymous" }

AI Interpretation

AI-powered reading interpretation, follow-up questions, and summarization. Requires Oracle tier or reading tokens.

POST/api/ai/interpretAccess Code10 per minute per IP

Generate an AI interpretation for a reading. Streams the response as text. Supports style, depth, cultural context, and second-opinion modes.

Parameters

Name	Type	Required	Description
accessCode	string	required	Access code (Oracle tier or token balance required)
systemId	string	required	Divination system ID
spreadType	string	required	Spread type slug
cards	Card[]	required	Drawn cards with positions, meanings, and reversal state
question	string	optional	The querent's question
style	string	optional	"mystical" \| "practical" \| "psychological" \| "poetic"
depth	string	optional	"standard" \| "glance" \| "deep"
secondOpinion	boolean	optional	Request an alternative perspective
culturalContext	string	optional	"western" \| "eastern" \| "celtic" \| "norse"
readingContext	string	optional	"general" \| "relationship" \| "career" \| "health" \| "spiritual"
plainLanguage	boolean	optional	Simplify language for beginners

Response

Streamed text/plain (Transfer-Encoding: chunked)

Example

curl -X POST https://chaos-tarot.com/api/ai/interpret \
  -H "Content-Type: application/json" \
  -d '{
    "accessCode": "XXXX-XXXX-XXXX",
    "systemId": "chaos-tarot",
    "spreadType": "single-card",
    "cards": [{"name": "The Zero Point", "positionName": "Present", ...}]
  }'

POST/api/ai/followupAccess Code10 per minute per IP

Ask a follow-up question about a previous AI interpretation.

Parameters

Name	Type	Required	Description
accessCode	string	required	Access code
question	string	required	Follow-up question
context	string	required	Previous interpretation text
systemId	string	required	System ID

Response

Streamed text/plain

POST/api/ai/summarizeAccess Code10 per minute per IP

Generate a concise summary/title for a reading interpretation. Controlled by the AI_SUMMARIZE feature flag.

Parameters

Name	Type	Required	Description
accessCode	string	required	Access code
interpretation	string	required	Full interpretation text
systemId	string	required	System ID

Response

{ "summary": "Brief reading summary...", "title": "The Zero Point Speaks" }

Daily Draws

Daily card/rune/hexagram/figure draws. One free draw per system per day for all tiers. Supports streak tracking and bonus draws.

GET/api/daily-drawAccess Code20 per minute per IP

Get today's tarot daily draw status and streak info.

Parameters

Name	Type	Required	Description
code	string (query)	required	Access code
tz	string (query)	optional	IANA timezone (e.g. America/New_York)

Response

{
  "todayDraw": { "card_id": "chaos-tarot:major:00-the-zero-point", ... } | null,
  "streak": { "current_streak": 7, "longest_streak": 30 },
  "hasDrawnToday": false,
  "hasBonusDraw": false
}

Example

curl "https://chaos-tarot.com/api/daily-draw?code=XXXX-XXXX-XXXX&tz=America/New_York"

POST/api/daily-drawAccess Code20 per minute per IP

Draw today's tarot card. Returns card data and updated streak.

Parameters

Name	Type	Required	Description
accessCode	string	required	Access code
timezone	string	optional	IANA timezone

Response

{ "draw": {...}, "card": { "id": "...", "name": "...", ... }, "streak": {...} }

GET/api/daily-draw/historyAccess Code

Retrieve daily draw history with pagination.

Parameters

Name	Type	Required	Description
code	string (query)	required	Access code
limit	number (query)	optional	Max results (default: 30)

Response

{ "draws": [...], "total": 90 }

GET/api/daily-runeAccess Code20 per minute per IP

Get/draw today's Elder Futhark rune.

Parameters

Name	Type	Required	Description
code	string (query)	required	Access code
tz	string (query)	optional	IANA timezone

Response

{ "todayDraw": {...}, "streak": {...}, "hasDrawnToday": false }

GET/api/daily-hexagramAccess Code20 per minute per IP

Get/draw today's I Ching hexagram.

Parameters

Name	Type	Required	Description
code	string (query)	required	Access code

Response

{ "todayDraw": {...}, "streak": {...}, "hasDrawnToday": false }

GET/api/daily-oghamAccess Code20 per minute per IP

Get/draw today's Ogham feda.

Parameters

Name	Type	Required	Description
code	string (query)	required	Access code

Response

{ "todayDraw": {...}, "streak": {...}, "hasDrawnToday": false }

GET/api/daily-lenormandAccess Code20 per minute per IP

Get/draw today's Lenormand card.

Parameters

Name	Type	Required	Description
code	string (query)	required	Access code

Response

{ "todayDraw": {...}, "streak": {...}, "hasDrawnToday": false }

GET/api/daily-geomancyAccess Code20 per minute per IP

Get/draw today's Geomancy figure.

Parameters

Name	Type	Required	Description
code	string (query)	required	Access code

Response

{ "todayDraw": {...}, "streak": {...}, "hasDrawnToday": false }

Stats & Progress

User statistics, collection progress, streak calendars, and public platform stats.

GET/api/stats/cardsAccess Code

Get card draw statistics and collection progress for the user.

Parameters

Name	Type	Required	Description
code	string (query)	required	Access code

Response

{ "totalDraws": 156, "uniqueCards": 45, "collections": {...} }

GET/api/stats/seen-cardsAccess Code

Get the set of cards/runes/items the user has encountered.

Parameters

Name	Type	Required	Description
code	string (query)	required	Access code
system	string (query)	optional	Filter by system ID

Response

{ "seenCards": ["chaos-tarot:major:00-the-zero-point", ...] }

GET/api/stats/streak-calendarAccess Code

Get a calendar of daily draw activity for streak visualization.

Parameters

Name	Type	Required	Description
code	string (query)	required	Access code
year	number (query)	optional	Year (default: current)
month	number (query)	optional	Month 1-12 (default: current)

Response

{ "days": { "2026-03-01": true, "2026-03-02": true, ... } }

GET/api/stats/publicPublic

Public platform-wide statistics (no auth required).

Response

{ "totalUsers": 1200, "totalReadings": 15000, "totalDailyDraws": 8000 }

Example

curl https://chaos-tarot.com/api/stats/public

Community

Community feed for sharing readings, boosting posts, and collective divination events.

GET/api/community/feedAccess Code

Get the community feed with shared readings.

Parameters

Name	Type	Required	Description
code	string (query)	required	Access code
page	number (query)	optional	Page number
tag	string (query)	optional	Filter by tag

Response

{ "posts": [...], "total": 200, "page": 1 }

POST/api/community/boostAccess Code

Boost (upvote) a community post.

Parameters

Name	Type	Required	Description
accessCode	string	required	Access code
postId	string	required	Community post ID

Response

{ "boosted": true, "totalBoosts": 12 }

POST/api/community/reportAccess Code

Report a community post for moderation.

Parameters

Name	Type	Required	Description
accessCode	string	required	Access code
postId	string	required	Post ID
reason	string	required	Report reason

Response

{ "reported": true }

GET/api/community/statsAccess Code

Get the user's community participation stats.

Parameters

Name	Type	Required	Description
code	string (query)	required	Access code

Response

{ "postsShared": 5, "totalBoosts": 23, "karmaScore": 42 }

GET/api/community/trendingAccess Code

Get trending tags and popular posts.

Response

{ "tags": [...], "topPosts": [...] }

GET/api/collective/questionsAccess Code

Get active collective divination questions.

Response

{ "questions": [...] }

POST/api/collective/voteAccess Code

Submit a vote/reading response for a collective question.

Parameters

Name	Type	Required	Description
accessCode	string	required	Access code
questionId	string	required	Question ID
cardId	string	required	Selected card/item ID

Response

{ "voted": true }

Astrology

Natal charts, transit tracking, synastry comparisons, and daily horoscopes.

POST/api/astrology/natalAccess Code

Calculate a natal chart from birth data.

Parameters

Name	Type	Required	Description
accessCode	string	required	Access code
birthDate	string	required	ISO date string
birthTime	string	optional	HH:MM format
latitude	number	required	Birth location latitude
longitude	number	required	Birth location longitude

Response

{ "planets": [...], "houses": [...], "aspects": [...] }

GET/api/astrology/transitsAccess Code

Get current planetary transits for a user's natal chart.

Parameters

Name	Type	Required	Description
code	string (query)	required	Access code

Response

{ "transits": [...], "significantAspects": [...] }

POST/api/astrology/synastryAccess Code

Compare two natal charts for relationship compatibility.

Parameters

Name	Type	Required	Description
accessCode	string	required	Access code
partnerBirthDate	string	required	Partner's ISO birth date
partnerLatitude	number	required	Partner's birth latitude
partnerLongitude	number	required	Partner's birth longitude

Response

{ "aspects": [...], "compatibility": {...} }

GET/api/astrology/horoscopeAccess Code

Get a daily horoscope based on the user's sun sign.

Parameters

Name	Type	Required	Description
code	string (query)	required	Access code

Response

{ "sign": "Aries", "horoscope": "...", "date": "2026-03-02" }

POST/api/astrology/birth-profileAccess Code

Save or update the user's birth data for recurring transit calculations.

Parameters

Name	Type	Required	Description
accessCode	string	required	Access code
birthDate	string	required	ISO date
birthTime	string	optional	HH:MM
location	string	required	Location name
latitude	number	required	Latitude
longitude	number	required	Longitude

Response

{ "saved": true }

GET/api/astrology/geocodeAccess Code

Geocode a location name to lat/lng for birth chart entry.

Parameters

Name	Type	Required	Description
q	string (query)	required	Location search query

Response

{ "results": [{ "name": "...", "lat": 40.7, "lng": -74.0 }] }

System & Health

Health checks, telemetry, and infrastructure endpoints.

GET/api/healthPublic

Comprehensive health check. Returns overall status (healthy/degraded/unhealthy) with per-service check results and feature flag states.

Response

{
  "status": "healthy",
  "timestamp": "2026-03-02T12:00:00Z",
  "uptime": 86400,
  "version": "abc1234",
  "checks": {
    "database": { "status": "pass", "latencyMs": 45 },
    "ai": { "status": "pass", "message": "..." },
    "stripe": { "status": "pass", "message": "..." },
    "email": { "status": "pass" },
    "environment": { "status": "pass" },
    "social": { "discord": true, ... }
  },
  "featureFlags": { ... }
}

Example

curl https://chaos-tarot.com/api/health

POST/api/telemetry/errorPublic30 per minute per IP

Report a client-side error for telemetry.

Parameters

Name	Type	Required	Description
message	string	required	Error message
stack	string	optional	Stack trace
url	string	optional	Page URL where error occurred
userAgent	string	optional	Browser user agent

Response

{ "logged": true }

POST/api/bug-reportAccess Code

Submit a user-generated bug report.

Parameters

Name	Type	Required	Description
accessCode	string	required	Access code
title	string	required	Bug title
description	string	required	Detailed description
category	string	optional	Bug category

Response

{ "id": "uuid", "status": "open" }

Error Codes

Status	Meaning	Common Causes
400	Bad Request	Missing/invalid parameters, malformed JSON
401	Unauthorized	Missing or invalid access code
403	Forbidden	Insufficient tier (e.g., AI requires Oracle), no tokens
409	Conflict	Already drawn today, duplicate entry
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error (logged automatically)
503	Service Unavailable	Feature disabled via flag, database down

All error responses include a JSON body with an error field containing a human-readable message.

Divination Systems

The following system IDs are used across all API endpoints that accept a systemId parameter.

System ID	Name	Items	Reversals
chaos-tarot	Chaos Tarot	79 cards	Yes
elder-futhark	Elder Futhark	24 runes	Yes (merkstave)
i-ching	I Ching	64 hexagrams	No (changing lines)
ogham	Ogham	25 feda	Yes (contra)
lenormand	Lenormand	36 cards	No
geomancy	Geomancy	16 figures	No
cross-system	Cross-System	Virtual	Varies

Start Building

Create a free account to get your access code and start making API requests.

Create Account View Pricing