API Reference
Welcome to the AstroAPI Reference documentation. This section provides detailed information about all available endpoints.
OpenAPI Specification
The complete API is documented using the OpenAPI 3.1 specification. Use the sidebar to browse available endpoints organized by category.
Base URL
https://api.astroapi.cloudAuthentication
All API requests require authentication via:
- API Key:
X-Api-Keyheader
See the Authentication Guide for details.
Response Format
All responses follow the JSON:API specification:
{
"data": {
"type": "resource-type",
"id": "resource-id",
"attributes": { ... }
}
}Error Responses
Errors follow JSON:API error format:
{
"errors": [{
"status": "400",
"title": "Bad Request",
"detail": "Detailed error message"
}]
}Common HTTP Status Codes
| Code | Description |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Missing or invalid authentication |
| 403 | Forbidden - Insufficient permissions or module access |
| 404 | Not Found |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |
Professional astrology API for natal charts, transits, synastry, and interpretations
Servers
Content
Content management and interpretation texts
Operations
Create Custom Copy
Create an organization-specific copy of system content for customization.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
Create a custom copy of system content
Restore Content
Restore custom content to match the original system content.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
Restore custom content to match system content
Delete Content by ID
Delete a content item by its ID.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
Delete one content item
List Content
Retrieve a paginated list of content items filtered by horoscope and content type.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
Retrieve content items
Create Content
Create a new content item for a specific horoscope and content type.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
Create content item
Get Content
Retrieve a single content item by its ID.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
Retrieve one content item
Delete Content
Delete a content item by horoscope type, content type, and ID.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
Delete one content item
Update Content
Update the title, body or metadata of a content item.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
Update one content item
Calculations
Astrological calculations including natal charts, transits, synastry, and more
Operations
Natal Chart
Calculate a natal (birth) chart with planetary positions, house cusps, and aspects. By default the Moon is topocentric (parallax-corrected for the birth location); set moonCenter to geocentric for Earth-center Moon positions.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Calculate natal chart
AI Summary (natal)
Generate a short narrative summary of what this horoscope means, written from the strongest placements and aspects of the chart. Open the signed summary.url returned by the matching calculation endpoint — it carries the whole request, so no body is needed. Generating a summary counts as 10 API requests and takes several seconds; a summary that was generated before is served from cache and counts as one. Requires the AI Summary module (included in the Premium and Deluxe plans) plus the interpretation texts of this horoscope type.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
The generated summary
Synastry Chart
Calculate synastry aspects between two birth charts for relationship analysis.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Calculate synastry chart
AI Summary (synastry)
Generate a short narrative summary of what this horoscope means, written from the strongest placements and aspects of the chart. Open the signed summary.url returned by the matching calculation endpoint — it carries the whole request, so no body is needed. Generating a summary counts as 10 API requests and takes several seconds; a summary that was generated before is served from cache and counts as one. Requires the AI Summary module (included in the Premium and Deluxe plans) plus the interpretation texts of this horoscope type.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
The generated summary
Composite Chart
Calculate a composite chart by combining midpoints of two birth charts.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Calculate composite chart
AI Summary (composite)
Generate a short narrative summary of what this horoscope means, written from the strongest placements and aspects of the chart. Open the signed summary.url returned by the matching calculation endpoint — it carries the whole request, so no body is needed. Generating a summary counts as 10 API requests and takes several seconds; a summary that was generated before is served from cache and counts as one. Requires the AI Summary module (included in the Premium and Deluxe plans) plus the interpretation texts of this horoscope type.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
The generated summary
Transit Chart
Calculate planetary transits over a natal chart for a specified time period.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Calculate transits chart
AI Summary (transit)
Generate a short narrative summary of what this horoscope means, written from the strongest placements and aspects of the chart. Open the signed summary.url returned by the matching calculation endpoint — it carries the whole request, so no body is needed. Generating a summary counts as 10 API requests and takes several seconds; a summary that was generated before is served from cache and counts as one. Requires the AI Summary module (included in the Premium and Deluxe plans) plus the interpretation texts of this horoscope type.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
The generated summary
Transit iCal Export
Generate an iCal (.ics) file containing transit aspects as calendar events.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
iCal file with transit aspects
Compatibility Analysis
Calculate sun sign compatibility between two people with interpretation text.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Calculate compatibility between two birth charts
Solar Return
Calculate the solar return chart for a specific year (birthday chart).
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Calculate solar return chart
AI Summary (solar)
Generate a short narrative summary of what this horoscope means, written from the strongest placements and aspects of the chart. Open the signed summary.url returned by the matching calculation endpoint — it carries the whole request, so no body is needed. Generating a summary counts as 10 API requests and takes several seconds; a summary that was generated before is served from cache and counts as one. Requires the AI Summary module (included in the Premium and Deluxe plans) plus the interpretation texts of this horoscope type.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
The generated summary
Lunar Return
Calculate the lunar return chart when the Moon returns to its natal position.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Calculate lunar return chart
AI Summary (lunar)
Generate a short narrative summary of what this horoscope means, written from the strongest placements and aspects of the chart. Open the signed summary.url returned by the matching calculation endpoint — it carries the whole request, so no body is needed. Generating a summary counts as 10 API requests and takes several seconds; a summary that was generated before is served from cache and counts as one. Requires the AI Summary module (included in the Premium and Deluxe plans) plus the interpretation texts of this horoscope type.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
The generated summary
Secondary Progressions
Calculate secondary progressions chart using the day-for-a-year method. Returns progressed planet positions and aspects to both progressed and natal planets.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Calculate secondary progressions chart
AI Summary (progressions)
Generate a short narrative summary of what this horoscope means, written from the strongest placements and aspects of the chart. Open the signed summary.url returned by the matching calculation endpoint — it carries the whole request, so no body is needed. Generating a summary counts as 10 API requests and takes several seconds; a summary that was generated before is served from cache and counts as one. Requires the AI Summary module (included in the Premium and Deluxe plans) plus the interpretation texts of this horoscope type.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
The generated summary
Moon & Sun Info
Get Moon and Sun information for a specific place and time. Includes moon phase, illumination, distance, and sun rise/set/twilight times.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Moon and Sun information
Moon Calendar Day
Get detailed moon calendar information for a single day, including void of course periods, moon phase, sign transits, and upcoming aspects.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Moon calendar day information
Moon Calendar Range
Get moon calendar information for a date range (max 31 days), including all void of course periods, major lunar phases, and sign transits.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Moon calendar range information
Retrograde Planets Calendar
Calculate retrograde periods for planets within a date range. Returns station dates (when planets turn retrograde/direct), shadow periods, signs traversed, and duration for each retrograde period.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Retrograde calendar data
Chinese Zodiac Sign
Calculate the Chinese zodiac sign and element based on birth year.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Calculate Chinese horoscope sign
Chinese Zodiac Forecast
Get Chinese zodiac forecast for a specific year with category breakdowns.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Calculate Chinese horoscope forecast
Render Chart (SVG)
Render an astrological chart as SVG image.
Required parameters:
- width, height: Chart dimensions
- dateTime: Natal date/time (YYYY-MM-DDTHH:mm)
- location.longitude, location.latitude, location.timezone: Natal location
Optional transit parameters (for bi-wheel chart):
- transit.dateTime: Transit date/time (YYYY-MM-DDTHH:mm)
- transit.timezone: Transit timezone
- transit.longitude, transit.latitude: Transit location (defaults to natal location)
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Query Parameters
Responses
Chart rendered successfully
Render Chart (PNG)
Render an astrological chart as PNG image. Requires query parameters: width, height, dateTime, location.longitude, location.latitude, location.timezone
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Query Parameters
Responses
Chart rendered successfully
Render Composite Chart (SVG)
Render a composite chart (midpoints of two natal charts) as SVG image.
Required parameters:
- width, height: Chart dimensions
- person1.dateTime: Person 1 date/time (YYYY-MM-DDTHH:mm)
- person1.timezone: Person 1 timezone
- person1.longitude, person1.latitude: Person 1 location
- person2.dateTime: Person 2 date/time (YYYY-MM-DDTHH:mm)
- person2.timezone: Person 2 timezone
- person2.longitude, person2.latitude: Person 2 location
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Query Parameters
Responses
Composite chart rendered successfully
Render Composite Chart (PNG)
Render a composite chart (midpoints of two natal charts) as PNG image.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Query Parameters
Responses
Composite chart rendered successfully
Render Natal Chart (SVG) - v2
Render a natal chart using the new Chart2 engine as SVG.
Required parameters:
- width, height: Chart dimensions
- dateTime: Birth date/time (YYYY-MM-DDTHH:mm)
- location.longitude, location.latitude, location.timezone: Birth location
Theme presets:
Use ?theme=<preset> to select a theme:
- default: Classic white background with colored elements
- classic: Traditional astrology chart look
- dark: Modern dark theme with vibrant colors
- minimal: Clean, less visual noise
- colorful: Vibrant planet colors
- nextgen: Modern design with curved aspect lines, glow effects, and gradients
- vintage: Old parchment/manuscript style with sepia tones
- neon: Cyberpunk style with bright neon colors on black
- pastel: Soft, calming pastel colors
- print: High contrast black/white optimized for printing
Optional theme overrides:
- theme.background: Background color
- theme.foreground: Text color
- theme.strokeOnly: Render stroke only (true/false)
- theme.symbolScale: Symbol scale factor
- theme.showDegrees: Show degree labels (true/false)
- theme.showHouseNumbers: Show house numbers (true/false)
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
Chart rendered successfully
Render Natal Chart (PNG) - v2
Render Transit Chart (SVG) - v2
Render a transit bi-wheel chart using the new Chart2 engine as SVG.
Required parameters:
- width, height: Chart dimensions
- dateTime: Natal date/time (YYYY-MM-DDTHH:mm)
- location.longitude, location.latitude, location.timezone: Natal location
- transit.dateTime: Transit date/time (YYYY-MM-DDTHH:mm)
Optional parameters:
- transit.timezone: Transit timezone (defaults to natal timezone)
- transit.longitude, transit.latitude: Transit location (defaults to natal location)
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
Chart rendered successfully
Render Transit Chart (PNG) - v2
Render Synastry Chart (SVG) - v2
Render a synastry comparison chart using the new Chart2 engine as SVG.
Required parameters:
- width, height: Chart dimensions
- person1.dateTime, person1.timezone: Person 1 birth date/time
- person1.longitude, person1.latitude: Person 1 birth location
- person2.dateTime, person2.timezone: Person 2 birth date/time
- person2.longitude, person2.latitude: Person 2 birth location
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
Chart rendered successfully
Render Synastry Chart (PNG) - v2
Render Composite Chart (SVG) - v2
Render a composite midpoint chart using the new Chart2 engine as SVG.
Required parameters:
- width, height: Chart dimensions
- person1.dateTime, person1.timezone: Person 1 birth date/time
- person1.longitude, person1.latitude: Person 1 birth location
- person2.dateTime, person2.timezone: Person 2 birth date/time
- person2.longitude, person2.latitude: Person 2 birth location
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
Chart rendered successfully
Render Composite Chart (PNG) - v2
Render Animated Transit Chart (SVG) - v2
Render an animated transit chart with CSS keyframe animations.
Required parameters:
- width, height: Chart dimensions
- dateTime: Natal date/time (YYYY-MM-DDTHH:mm)
- location.longitude, location.latitude, location.timezone: Natal location
- transit.dateTime: Start transit date/time
- target.dateTime: End transit date/time (animation target)
- animation.duration: Animation duration in milliseconds
Optional parameters:
- animation.easing: Easing function (linear, easeIn, easeOut, easeInOut, bounce)
- animation.loop: Loop animation (true/false)
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
Animated chart rendered successfully
Create Organization
Create a new organization with Stripe billing setup.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Create organization
List Members
Get a paginated list of organization members.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
List organization users
Add Member
Add or invite a new member to the organization.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Member toegevoegd/uitgenodigd
Remove Member
Update Member
Update an organization member's role.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
1Request Body
Responses
Member geüpdatet
Get Overage Setting
Get the current overage billing setting for the organization.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
Overage setting
Toggle Overage Billing
Enable or disable overage billing for the current organization.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Overage setting updated
Choose Language
Gold plan users choose their one extra language.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Language updated
Get Pinned API Version
Get the API compatibility date this organization is pinned to. A null pin means requests without an X-Api-Version header get the baseline version.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
Pinned API version
Pin API Version
Pin the organization to an API compatibility date, or send null to fall back to the baseline version.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Pinned API version updated
List Modules
Get all available modules with pricing information.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
List all available modules
Organization Modules
Get the list of modules the current organization has access to.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
List modules for current organization
Subscription Plans
Get all available subscription plans with included modules and pricing.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
List all subscription plans
Check Module Access
Check if the current organization has access to a specific module.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
Check module access
List Available Modules
Get all available modules with pricing information. No authentication required.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
List of all available modules
List Subscription Plans
Get all available subscription plans with included modules and pricing. No authentication required.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
List of all subscription plans
Calculate Custom Price
Calculate the total price for a custom selection of modules. No authentication required.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
Calculated price information
Get Invitation Details
Look up a pending organization invitation by id. Used by the accept-invitation page to render the form before the invitee has signed up.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
Invitation details
List API Keys
Get all API keys owned by the current user.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
List of API keys
Create API Key
Create a new API key with optional permission and module restrictions.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
API key created
Available Options
Get available permissions and feature permissions for configuring API keys.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
Available options
API Key Usage Statistics
Get aggregate usage statistics across all API keys for the current user.
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
Usage statistics
Get API Key
Get details of a specific API key.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
API key details
Delete API Key
Delete an API key and revoke it. The key disappears from the API immediately; tokens already issued for it stop working within a few minutes, once the revocation list has been refreshed.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
API key deleted
Update API Key
Update an API key's settings. The key is rotated: a new key with a new id is returned once, and the previous key is revoked.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
API key updated and regenerated
Get Daily Horoscopes
Retrieve daily horoscopes for all zodiac signs for a specific date.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
"^\\d{4}-\\d{2}-\\d{2}$"Responses
Daily horoscopes for all zodiac signs
Get Weekly Horoscope Report
Retrieve weekly horoscope report for a specific zodiac sign and week.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
"^\\d{4}$""^(0[1-9]|[1-4]\\d|5[0-3])$"Responses
Weekly horoscope report
Get Yearly Horoscope Report
Retrieve yearly horoscope report for a specific zodiac sign and year.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
"^\\d{4}$"Responses
Yearly horoscope report
Get Yearly Ascendant Horoscope Report
Retrieve yearly horoscope report for a specific ascendant sign and year.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
"^\\d{4}$"Responses
Yearly ascendant horoscope report
Full Numerology Profile
Calculate a complete numerology profile including Life Path, Expression, Soul Urge, Personality, Birthday numbers, Personal Cycles, and identify Master/Karmic numbers.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Complete numerology profile
Life Path Number
Calculate the Life Path Number from birth date. This is the most important number in numerology, representing your life's purpose.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Life Path number calculation
Expression Number
Calculate the Expression (Destiny) Number from full name. This number reveals your natural talents and abilities.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Expression number calculation
Soul Urge Number
Calculate the Soul Urge (Heart's Desire) Number from vowels in the name. This number reveals your inner motivations.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Soul Urge number calculation
Personality Number
Calculate the Personality Number from consonants in the name. This number reveals how others perceive you.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Personality number calculation
Birthday Number
Calculate the Birthday Number from the day of birth. This number represents a special talent you possess.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Birthday number calculation
Personal Cycles
Calculate Personal Year, Month, and Day numbers. These reveal the current energetic influences in your life.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Personal cycles calculation
Numerology Compatibility
Calculate compatibility between two people based on their Life Path numbers.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Compatibility calculation
Human Design
Human Design Chart
Calculate a complete Human Design bodygraph chart including Type, Strategy, Authority, Profile, Definition, gate activations, channels, and centers.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Complete Human Design chart
Render Bodygraph (SVG)
Render a Human Design bodygraph chart as SVG.
Required parameters:
- dateTime: Birth date/time (YYYY-MM-DDTHH:mm, local time)
- latitude, longitude: Birth location
- timezone: IANA timezone identifier
Theme presets:
Use ?theme=<preset> to select a theme: default, dark, classic, minimal
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Query Parameters
Birth date and time in YYYY-MM-DDTHH:mm format (local time)
Birth latitude
-9090Birth longitude
-180180IANA timezone identifier (e.g. "Europe/Amsterdam")
1002000"576"1002000"480"Theme preset: default, dark, classic, minimal
Render Design/Personality planet columns (default true)
"true"Responses
Bodygraph SVG
Render Bodygraph (PNG)
Render a Human Design bodygraph chart as PNG.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Query Parameters
Birth date and time in YYYY-MM-DDTHH:mm format (local time)
Birth latitude
-9090Birth longitude
-180180IANA timezone identifier (e.g. "Europe/Amsterdam")
1002000"576"1002000"480"Theme preset: default, dark, classic, minimal
Render Design/Personality planet columns (default true)
"true"Responses
Bodygraph PNG
Chatbot
Operations
List Chatbots
Create Chatbot
Create a new chatbot for the organization
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Created chatbot
List Available Plugins
List Available Plugins for Organization
List chatbot plugins available to the current organization based on their subscribed modules
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
List of available plugins
Get Monthly Chatbot Usage
Get Chatbot Usage
Get Chatbot
Delete Chatbot
Update Chatbot
Update an existing chatbot
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
Updated chatbot
Get Chatbot Usage Statistics
Get usage statistics for a specific chatbot in the current month
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
Usage statistics
List Chat Profiles
Create Chat Profile
Create a pre-configured chat profile with birth data
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
Created profile
Delete Chat Profile
Chat with Chatbot
Send a message to a chatbot and receive a streaming response via SSE
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
SSE stream with chat response
Chat with Profile
Send a message using a pre-configured user profile
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
SSE stream with chat response
Chat with Birth Data
Send a message with inline birth data (no profile needed)
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
SSE stream with chat response
Get Conversation
Retrieve conversation history
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
Conversation data
Delete Conversation
Delete a conversation and its history
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
Conversation deleted
PDF Reports
Operations
List PDF Templates
List all PDF templates available to the current organization (org-specific + global). Pagination is opt-in: pass page[size] and/or page[number] (zero-based) to receive a slice with meta.page, meta.pageSize and links.next. Without them the full list is returned.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Query Parameters
Templates per page (default 10, max 100). Enables pagination.
1100Zero-based page number (default 0). Enables pagination.
0Responses
List of PDF templates
Create PDF Template
Create a new PDF template for the organization. Global admins can pass isGlobal: true to create a global template shared by all organizations.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Created PDF template
List Global PDF Templates
List all global (shared) PDF templates
Authorizations
API key for authentication. Get your API key from the dashboard.
Responses
List of global PDF templates
Get PDF Template
Get a specific PDF template by ID
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
PDF template details
Delete PDF Template
Delete a PDF template. Global templates can only be deleted by global admins.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
Template deleted
Update PDF Template
Update an existing PDF template. The report type is fixed after creation. Global templates can only be updated by global admins.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
Updated PDF template
Duplicate PDF Template
Duplicate a template (global or own) to the organization
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
Duplicated PDF template
Set Default PDF Template
Set a template as the default for its report type within the organization. Global admins can also set a global template as the global default.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Responses
Template set as default
Generate PDF Report
Generate a PDF report based on astrology calculations. transitDate (alias: targetDate) selects the date for transit, return and progression reports.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Generated PDF file
Preview PDF Template
Preview a PDF template as HTML with sample data. Pass either templateId for a saved template or draft for an unsaved one (exactly one of the two).
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
HTML preview
List Widgets
Create Widget
Create a new embeddable widget with auto-generated API key
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Created widget with API key
Get Widget Options
Get Widget
Delete Widget
Update Widget
Update an existing widget configuration
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
Updated widget
Regenerate API Key
Widget API
Operations
Get Widget Configuration
Calculate Natal Chart
Calculate natal chart via embedded widget
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
Natal chart data
Calculate Synastry Chart
Calculate synastry chart via embedded widget
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
Synastry chart data
Calculate Transit Chart
Calculate transit chart via embedded widget
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
Transit chart data
Calculate Composite Chart
Calculate composite chart via embedded widget
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
Composite chart data
Get Moon Phase
Get moon phase information via embedded widget
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
Moon phase data
Get Daily Horoscope
Get daily horoscope for a zodiac sign via embedded widget
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
Daily horoscope data
Calculate Numerology
Calculate numerology profile via embedded widget
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
Numerology data
Calculate Compatibility
Calculate numerology-based compatibility via embedded widget
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
Compatibility data
Get Moon Calendar
Get moon phase data for a full month via embedded widget
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
Moon calendar data
Search Places
Search for places by name via embedded widget. Returns coordinates and timezone.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Query Parameters
2100Responses
List of matching places
Get Widget Configuration
Widget Chat
Send a message via widget (SSE streaming response)
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
SSE stream with chat response
Widget Chat with User Profile
Chat using an external user ID (creates profile on first use)
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Path Parameters
Request Body
Responses
SSE stream with chat response
Search Places
Search for cities, towns, and places by name. Returns coordinates and location details for use with calculation endpoints.
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Query Parameters
2100Responses
List of matching places with coordinates
Render Astrocartography Map (SVG)
Render an astrocartography world map showing planetary lines for a birth moment.
Each line shows where a planet is angular (conjunct an angle) at that moment:
- MC lines (solid vertical): Where the planet culminates (on the Midheaven)
- IC lines (dashed vertical): Where the planet is at the lowest point (Imum Coeli)
- ASC lines (solid curved): Where the planet is rising (on the Ascendant)
- DSC lines (dashed curved): Where the planet is setting (on the Descendant)
Required parameters:
- dateTime: Birth date/time (YYYY-MM-DDTHH:mm)
- location.longitude, location.latitude, location.timezone: Birth location
Optional parameters:
- width, height: Map dimensions (default: 1200x600)
- projection: Map projection (equirectangular, naturalEarth1, mercator)
- showLabels, showLegend, showGraticule: Toggle map features (true/false)
- backgroundColor, landColor, oceanColor, borderColor, graticuleColor: Custom colors (hex)
- lineWidth: Line thickness in pixels
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Query Parameters
Birth date/time (YYYY-MM-DDTHH:mm)
Birth longitude in decimal degrees
Birth latitude in decimal degrees
IANA timezone identifier
Map width in pixels
"1200"Map height in pixels
"600"Map projection type
"equirectangular""naturalEarth1""mercator""equirectangular"Show planet line labels
"true"Show planet legend
"true"Show grid lines
"true"Background color (hex)
Land color (hex)
Ocean color (hex)
Country border color (hex)
Graticule grid line color (hex)
Line width in pixels
Responses
Astrocartography map rendered successfully
Render Astrocartography Map (PNG)
Render an astrocartography world map showing planetary lines for a birth moment.
Each line shows where a planet is angular (conjunct an angle) at that moment:
- MC lines (solid vertical): Where the planet culminates (on the Midheaven)
- IC lines (dashed vertical): Where the planet is at the lowest point (Imum Coeli)
- ASC lines (solid curved): Where the planet is rising (on the Ascendant)
- DSC lines (dashed curved): Where the planet is setting (on the Descendant)
Required parameters:
- dateTime: Birth date/time (YYYY-MM-DDTHH:mm)
- location.longitude, location.latitude, location.timezone: Birth location
Optional parameters:
- width, height: Map dimensions (default: 1200x600)
- projection: Map projection (equirectangular, naturalEarth1, mercator)
- showLabels, showLegend, showGraticule: Toggle map features (true/false)
- backgroundColor, landColor, oceanColor, borderColor, graticuleColor: Custom colors (hex)
- lineWidth: Line thickness in pixels
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Query Parameters
Birth date/time (YYYY-MM-DDTHH:mm)
Birth longitude in decimal degrees
Birth latitude in decimal degrees
IANA timezone identifier
Map width in pixels
"1200"Map height in pixels
"600"Map projection type
"equirectangular""naturalEarth1""mercator""equirectangular"Show planet line labels
"true"Show planet legend
"true"Show grid lines
"true"Background color (hex)
Land color (hex)
Ocean color (hex)
Country border color (hex)
Graticule grid line color (hex)
Line width in pixels
Responses
Astrocartography map rendered successfully
Calculate Astrocartography Lines (JSON)
Calculate astrocartography line data without rendering.
Returns the raw line coordinates for each planet and angle type,
useful for custom rendering or integration with mapping libraries.
Required parameters:
- dateTime: Birth date/time (YYYY-MM-DDTHH:mm)
- location.longitude, location.latitude, location.timezone: Birth location
Authorizations
API key for authentication. Get your API key from the dashboard.
Parameters
Query Parameters
Birth date/time (YYYY-MM-DDTHH:mm)
Birth longitude in decimal degrees
Birth latitude in decimal degrees
IANA timezone identifier
Map width in pixels
"1200"Map height in pixels
"600"Map projection type
"equirectangular""naturalEarth1""mercator""equirectangular"Show planet line labels
"true"Show planet legend
"true"Show grid lines
"true"Background color (hex)
Land color (hex)
Ocean color (hex)
Country border color (hex)
Graticule grid line color (hex)
Line width in pixels
Responses
Astrocartography lines calculated successfully
Legacy
Operations
Legacy Natal Chart
Accepts the old Bloom API request format and returns the natal chart in the legacy response format.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Natal chart in legacy format
Legacy Synastry
Accepts the old Bloom API request format and returns the synastry aspects in the legacy response format.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Synastry in legacy format
Legacy Composite Chart
Accepts the old Bloom API request format and returns the composite chart in the legacy response format.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Composite chart in legacy format
Legacy Transits
Accepts the old Bloom API request format and returns the transits in the legacy response format.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Transits in legacy format
Legacy Progressions
Accepts the old Bloom API request format and returns the progressions in the legacy response format.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Progressions in legacy format
Legacy Solar Return
Accepts the old Bloom API request format and returns the solar return chart in the legacy response format.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Solar return chart in legacy format
Legacy Lunar Return
Accepts the old Bloom API request format and returns the lunar return chart in the legacy response format.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Lunar return chart in legacy format
Legacy Chinese Forecasts
Accepts the old Bloom API request format and returns the Chinese zodiac forecast in the legacy response format.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Chinese forecast in legacy format
Legacy Compatibility
Accepts the old Bloom API request format and returns the compatibility analysis in the legacy response format.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Compatibility analysis in legacy format
Legacy Planet in Sign
Accepts the old Bloom API request format and returns the planet-in-sign interpretation in the legacy response format.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Planet-in-sign interpretation in legacy format
Legacy Sign to Sign
Accepts the old Bloom API request format and returns the sign-to-sign compatibility interpretation in the legacy response format.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Sign-to-sign interpretation in legacy format
Legacy Weekly Reports
Accepts the old Bloom API request format and returns weekly horoscope reports in the legacy response format.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Weekly reports in legacy format
Legacy Monthly Reports
Accepts the old Bloom API request format and returns monthly horoscope reports in the legacy response format.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Monthly reports in legacy format
Legacy Yearly Reports
Accepts the old Bloom API request format and returns yearly horoscope reports in the legacy response format.
Authorizations
API key for authentication. Get your API key from the dashboard.
Request Body
Responses
Yearly reports in legacy format