Authentication

All API requests require a Bearer token in the Authorization header.

Making authenticated requests

API keys follow the format thd_ followed by 24 alphanumeric characters. Generate keys from your API Keys dashboard.

Tier-based access

Your API key grants access based on the tier you subscribe to. Access is organised around two surfaces, each with its own meter.

Chart API surface

Covers all chart generation, astrology, and transit endpoints, and counts against your Chart requests meter:

/api/chart, /api/composite, /api/astrology, /api/transits/*, /api/retrogrades, /api/returns, /api/multi-chart

Unlocked by the Chart, Advanced, and Pro tiers (and the Free floor every key carries).

SAGE API surface

AI-powered knowledge engine, and counts against your SAGE responses meter:

/api/sage

Unlocked by the SAGE, Advanced, and Pro tiers (and the Free floor every key carries). A Chart-only key cannot answer SAGE queries beyond the small Free floor. Subscribe to a tier that covers SAGE, or stack a SAGE subscription on top of your Chart one.

The MCP server (/mcp) wraps both surfaces. Each tool requires the surface it calls, so an MCP key can run chart tools, SAGE tools, or both, depending on the tier.

Subscriptions stack: you can hold several active tiers at once and their allowances add. Each surface's rate limits and meter usage are tracked independently on the same key. See Endpoint Access by Tier for the full table.

Key management

• You can create up to 10 API keys per account
• Keys are shown only once at creation — store them securely
• Revoke compromised keys immediately from your dashboard
• Each key inherits the products from your current subscription

Error responses

If your key is missing, invalid, or lacks access to the requested endpoint:

See the full Error Codes reference for all possible error responses.