The only OpenAI-compatible agentic platform for astrology.
16 server-side tools, BYOK model choice, SSE streaming, multi-subject sessions. One API call, full agent loop.
The Chat API orchestrates these endpoints automatically, but you can also use them directly:
Real conversations powered by server-side tool orchestration
import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://api.astrology-api.io/api/v3/chat", apiKey: "your-astrology-api-key",});
const response = await client.chat.completions.create({ model: "astro-default", stream: true, messages: [ { role: "system", content: "Warm, insightful astrologer." }, { role: "user", content: "Analyze my natal chart" } ], astrology: { subjects: [{ id: "me", birth_data: { year: 1990, month: 3, day: 15, hour: 14, minute: 30, city: "New York", country_code: "US" } }], enabled_tools: ["charts_natal"], defaults: { language: "en", tradition: "psychological" } }} as any);
for await (const chunk of response) { process.stdout.write(chunk.choices[0]?.delta?.content || "");}Works with any of our 16 endpoints or combinations
Any endpoint combination in one session โ natal, Vedic, horary, BaZi, astrocartography, and more.25 credits/turn ยท 2 with BYOK ยท + endpoint costs
Enterprise-grade speed, developer-friendly pricing
Everything you need to build AI astrology experiences
Everything you need to build AI-powered astrology experiences
What if you could add a fully-functional astrology AI agent to your app with a single API call? That's exactly what the Astrology Chat API does. It's not just a chatbot endpoint โ it's a complete agentic platform that runs the entire tool-calling loop server-side. You send a user message, and the server autonomously decides which of 16 astrology tools to invoke, resolves birth chart data from subject IDs (no hallucinated dates), generates PDF reports or SVG charts as binary artifacts, and returns a coherent response โ all through an OpenAI-compatible /chat/completions endpoint. That means you can use the standard OpenAI SDK in TypeScript, Python, Go, or any language. No custom integration code. No building your own agent framework. No managing tool schemas. Existing astrology chat solutions charge $0.25-$0.87 per query, take 8-24 seconds to respond, lock you into proprietary models, and use custom JSON formats that require bespoke integration code. We're the only platform that ships a ready-made agent with BYOK support โ choose your own LLM from GPT-5, Claude, Gemini, Grok, or any of 50+ models on OpenRouter.
The Astrology Chat API works like a specialized AI agent that happens to know astrology deeply.
Here's the flow: 1) You send a message via the standard OpenAI /chat/completions endpoint.
2) The server injects astrological context โ your subjects' birth data, active tools, language preferences.
3) The LLM decides which tools to call (natal chart calculation, transit analysis, synastry report, etc.).
4) The server executes those tools internally against our 82 astrology endpoints โ no extra API calls from your side.
5) Tool results are fed back to the LLM for synthesis.
6) You receive a coherent, grounded interpretation with real planetary data.
The entire tool loop runs server-side in a single request.
You never see tool-call messages โ just the final answer.
With streaming enabled (SSE), you also get real-time extension events like tool_start and tool_end, so your UI can show 'Calculating transit chart...' while the agent works.
BYOK โ Bring Your Own Key โ means you choose which LLM powers your astrology agent.
Every other astrology chat solution on the market locks you into a single proprietary model with no alternatives โ some don't even disclose which model they use.
With our BYOK endpoint (/chat/completions/byok), you pass your own API key and model ID.
We support three providers: OpenAI (GPT-5, GPT-5-mini, GPT-5-nano, o3, o4), Anthropic (Claude Opus 4, Claude Sonnet 4, Claude Haiku 4), and OpenRouter (50+ models including Gemini 3, Grok 4, Llama, Mistral, and more).
Why does this matter? Cost control โ GPT-5-nano is 10x cheaper than GPT-5-pro.
Quality tuning โ Claude excels at nuanced interpretation, Gemini is faster for simple queries.
Compliance โ some enterprises require specific model providers.
BYOK costs just 2 credits/turn (our platform fee) plus whatever your LLM provider charges.
OpenAI compatibility means you use the standard OpenAI SDK โ the same client library millions of developers already know.
No new SDK to learn, no custom HTTP client to build.
In TypeScript: new OpenAI({ baseURL: 'https://api.astrology-api.io/api/v3/chat' }).
In Python: OpenAI(base_url='...').
That's it.
Your existing code for ChatGPT works with minimal changes.
This also means instant compatibility with every framework built on OpenAI's protocol: LangChain, LlamaIndex, Vercel AI SDK, Semantic Kernel, AutoGen, CrewAI.
If your framework speaks OpenAI, it speaks Astrology Chat API.
No other astrology provider offers this โ existing solutions use custom endpoints with proprietary request/response shapes, requiring bespoke integration code for every platform you support.
The platform exposes 16 tools that the LLM can autonomously invoke during a conversation.
These are auto-generated from our 82 existing API endpoints using a dynamic registry โ only endpoints tagged 'chat-safe' become tools.
The tools cover: Analysis (3 tools) โ natal reports with multi-section interpretations, lunar analysis with moon phases and mansions, synastry reports with relationship index scores.
Chart Calculations (4 tools) โ natal, synastry, composite, and transit charts with full planetary positions and aspects.
Chart Rendering (4 tools) โ natal, synastry, transit, and composite charts as SVG, PNG, JPG, WebP, or PDF.
Generated charts are stored as binary artifacts with shareable URLs.
Data (3 tools) โ current planetary positions, ephemeris for any date, and aspect matrices.
Horoscope (1 tool) โ personalized daily horoscope with 6 life areas, ratings, and planetary influences.
PDF (1 tool) โ professional multi-page natal report with wheel visualization, interpretations, and themes.
Adding new tools requires zero code changes to the chat endpoint โ just tag an existing endpoint as 'chat-safe'.
Two features no competitor offers: multi-subject sessions and binary artifacts.
Multi-subject means you can pass multiple birth charts in a single conversation โ for example, 'me' and 'partner'.
The LLM references subjects by their semantic ID when calling tools, and the server resolves them to full birth data.
This enables synastry analysis, composite chart comparisons, and family dynamics โ all in one chat session, without re-sending birth data.
No other chat API supports more than one subject per conversation.
Binary artifacts let the chat generate downloadable files.
Ask 'Generate my natal chart' and receive an SVG chart image.
Ask 'Create a PDF report' and get a professional multi-page document.
Artifacts are stored in Supabase with shareable URLs and 24-hour retention.
Sessions persist via Redis with a 24-hour sliding TTL.
Pass the same session_id across turns and the server restores conversation history, subjects, and context โ true multi-turn memory without client-side state management.
Let's talk numbers.
The fastest competing astrology chat solutions take 8-12 seconds per response.
Standard-tier plans on the market average 19-24 seconds.
Our calculation layer responds in under 300ms โ total response time depends only on LLM speed, typically 2-5 seconds with streaming.
That's 4-10x faster.
On pricing, alternatives charge $0.25-$0.87 per AI query โ on top of monthly subscription fees.
Our hosted mode costs 25 credits per turn (about $0.02 on Professional plan).
BYOK mode costs just 2 credits per turn (~$0.001) โ you only pay your LLM provider directly.
That's 10-100x cheaper per conversation turn.
Most competitors don't even publish transparent chat pricing, relying on opaque credit systems.
We include chat in our standard free tier: 50 requests per month, no credit card required.
Add a conversational AI astrologer to your iOS or Android app. Users ask questions in natural language, get personalized interpretations backed by real chart calculations. OpenAI SDK works natively with React Native and Flutter.
Multi-subject sessions enable real-time compatibility analysis between two users. The agent calculates synastry, composite charts, and relationship dynamics โ all in a single conversation flow.
Generate personalized horoscopes, weekly forecasts, and natal reports at scale. BYOK with a cost-efficient model (GPT-5-nano) and batch process 10,000+ users for daily email or push notification content.
Integrate astrological insights into mindfulness apps, therapy tools, and self-reflection platforms. The psychological tradition mode provides Jungian-style interpretations focused on growth and self-awareness.
White-label the entire agent as your own product. Custom system prompts set the personality, BYOK controls costs, and session persistence enables multi-turn consultations for paying subscribers.
Plug directly into LangChain, CrewAI, AutoGen, or any OpenAI-compatible agent framework. Our API becomes a specialized astrology tool in your multi-agent system โ no custom adapters needed.
| API Protocol | OpenAI Chat Completions (v1) |
| Endpoints | /chat/completions (hosted) + /chat/completions/byok |
| Agent Tools | 16 auto-generated from 82 endpoints |
| Calculation Speed | <300ms per tool call |
| Total Response Time | 2-5s with streaming |
| Streaming | SSE with tool_start/tool_end extension events |
| BYOK Providers | OpenAI, Anthropic, OpenRouter (50+ models) |
| Hosted Model | astro-default (optimized for astrology) |
| Session Persistence | Redis-backed, 24h sliding TTL |
| Multi-Subject | Unlimited subjects per session |
| Binary Artifacts | SVG, PNG, JPG, WebP, PDF via chat |
| Languages | 9 (en, de, fr, es, it, pt, ru, zh, hi) |
| Traditions | Classical, Psychological, Event-Oriented, Universal |
| Authentication | Bearer token (API key) |
| Rate Limiting | Per API key, configurable |
| Feature | Astrology API | Others |
|---|---|---|
| OpenAI SDK Compatible | Yes (drop-in) | No (custom APIs) |
| BYOK Model Choice | 50+ models (3 providers) | Locked proprietary model |
| Server-Side Agent Loop | 16 tools, automatic | Build it yourself |
| Multi-Subject Sessions | Unlimited subjects | Single birth chart |
| Binary Artifacts | PDF, SVG, PNG via chat | Not available |
| Response Time | 2-5s (streaming) | 8-24 seconds |
| Price Per Query | $0.001-$0.02 | $0.25-$0.87 |
| Streaming | SSE + extension events | Basic or none |
| Free Tier | 50 requests/month | None or paid sandbox |
Calculate complete natal charts with planetary positions, houses, and aspects
Relationship compatibility analysis between two charts
Current planetary transits and their effects on natal charts
Generate professional multi-page astrology PDF reports
Complete technical reference with interactive examples
Start free, scale as you grow. No hidden fees, no surprises.
For small apps and personal projects
For growing apps and medium traffic
For enterprise-scale applications
All plans include comprehensive documentation and SDKs
Questions? Talk to our team
Real answers about the agentic astrology platform