Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Roxy Western Astrology API
version: 2.0.0
description: '# RoxyAPI: AI-Native Insight Infrastructure
> **Base URL:** `https://roxyapi.com/api/v2`
> All endpoint paths below are relative to this base URL.'
contact:
name: RoxyAPI Support
url: https://roxyapi.com/contact
license:
name: Proprietary
url: https://roxyapi.com/policy/terms
servers:
- url: /api/v2
description: Production API v2
security:
- apiKey: []
tags:
- name: Western Astrology
description: Western astrology API for natal birth charts, daily, weekly, monthly, and yearly horoscopes with unique content per sign and the dated sky events behind every reading, synastry compatibility scores, composite charts, solar and lunar returns, real-time transit aspects, and moon phases.
paths:
/astrology/signs:
get:
operationId: listZodiacSigns
tags:
- Western Astrology
summary: Get all zodiac signs - Complete zodiac signs list with dates and elements
description: 'Returns all 12 tropical zodiac signs (Aries, Taurus, Gemini, Cancer, Leo, Virgo, Libra, Scorpio, Sagittarius, Capricorn, Aquarius, Pisces) with essential information: name, symbol, element (fire, earth, air, water), date ranges, and short descriptions. Perfect for zodiac sign lists, horoscope widgets, birth chart calculators, astrology apps, star sign selectors, and zodiac reference tools. Use GET /signs/{id} for complete zodiac sign profiles with personality traits, compatibility, and detailed characteristics.'
security:
- apiKey: []
parameters:
- schema:
type: string
enum:
- en
- tr
- de
- es
- hi
- pt
- fr
- ru
- zh-Hans
- zh-Hant
default: en
example: en
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
required: false
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
name: lang
in: query
responses:
'200':
description: Successfully retrieved all 12 zodiac signs
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
example: aries
description: Lowercase sign identifier (e.g., aries, taurus, gemini).
name:
type: string
example: Aries
description: Display name of the zodiac sign.
symbol:
type: string
example: ♈
description: Unicode zodiac symbol for this sign.
element:
type: string
enum:
- fire
- earth
- air
- water
example: fire
description: 'Elemental classification: fire, earth, air, or water. Always one of these four English literals, whatever the lang parameter says, so it stays safe to compare against in code. Use elementLocalized for anything a reader sees.'
elementLocalized:
type: string
example: Fuego
description: Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
dates:
type: object
properties:
start:
type: string
example: Mar 21
description: Start date of this sign in the tropical zodiac.
end:
type: string
example: Apr 19
description: End date of this sign in the tropical zodiac.
required:
- start
- end
description: Tropical zodiac date range for this sign.
description:
type: string
example: Ambitious, independent, impatient
description: Brief overview of this zodiac sign personality and themes.
required:
- id
- name
- element
- dates
- description
description: All 12 tropical zodiac signs with names, symbols, elements, date ranges, and descriptions.
'400':
description: Validation error. `issues[]` lists every failed field.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: First issue summary.
code:
type: string
enum:
- validation_error
issues:
type: array
description: Every validation failure. Use this to rebuild a valid request.
items:
type: object
properties:
path:
type: string
description: Dot-separated field path, or "(root)" for top-level.
message:
type: string
code:
type: string
description: Zod issue code (invalid_type, too_small, too_big, invalid_string, ...).
expected:
type: string
description: Expected type for invalid_type.
minimum:
description: Minimum bound for too_small issues.
oneOf:
- type: number
- type: string
maximum:
description: Maximum bound for too_big issues.
oneOf:
- type: number
- type: string
inclusive:
type: boolean
format:
type: string
description: Format name for string issues (regex, email, url, uuid).
pattern:
type: string
description: Regex pattern when format is regex.
required:
- path
- message
required:
- error
- code
- issues
'401':
description: Invalid or missing API key
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'405':
description: Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
headers:
Allow:
description: Comma-separated list of allowed methods (RFC 9110).
schema:
type: string
content:
application/json:
schema:
type: object
properties:
error:
type: string
code:
type: string
enum:
- method_not_allowed
allow:
type: array
items:
type: string
description: Allowed HTTP methods for this path. Mirrors the Allow response header.
docs:
type: string
description: Link to the product page for this domain.
required:
- error
- code
- allow
'429':
description: Monthly rate limit exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'500':
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
/astrology/signs/{id}:
get:
operationId: getZodiacSign
tags:
- Western Astrology
summary: Get zodiac sign details - Complete astrology sign profile with personality…
description: 'Retrieve comprehensive zodiac sign information for any astrological sign using lowercase ID (e.g., "aries") or case-insensitive name (e.g., "Aries", "ARIES"). Returns complete astrology profile including: element (fire, earth, air, water), modality (cardinal, fixed, mutable), ruling planet, birth date ranges, personality traits (positive, negative, keywords), zodiac sign descriptions, famous people with this sign, key strengths and qualities, sign motto, greatest gifts, challenges, and secret weapon. Perfect for horoscope readings, zodiac compatibility checks, birth chart interpretations, astrology blogs, star sign personality analysis, and zodiac meaning databases.'
security:
- apiKey: []
parameters:
- schema:
type: string
example: aries
description: Sign ID (lowercase, e.g., aries, taurus) or display name (case-insensitive, e.g., Aries, TAURUS).
required: true
description: Sign ID (lowercase, e.g., aries, taurus) or display name (case-insensitive, e.g., Aries, TAURUS).
name: id
in: path
- schema:
type: string
enum:
- en
- tr
- de
- es
- hi
- pt
- fr
- ru
- zh-Hans
- zh-Hant
default: en
example: en
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
required: false
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
name: lang
in: query
responses:
'200':
description: Successfully retrieved zodiac sign
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: aries
description: Lowercase sign identifier.
name:
type: string
example: Aries
description: Display name of the zodiac sign.
symbol:
type: string
example: ♈
description: Unicode zodiac symbol.
symbolName:
type: string
example: The Ram
description: Symbol name or mascot associated with this sign.
element:
type: string
enum:
- fire
- earth
- air
- water
example: fire
description: 'Elemental classification: fire, earth, air, or water. Determines temperament and compatibility group. Always one of these four English literals, whatever the lang parameter says, so it stays safe to compare against in code. Use elementLocalized for anything a reader sees.'
elementLocalized:
type: string
example: Fuego
description: Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
modality:
type: string
enum:
- cardinal
- fixed
- mutable
example: cardinal
description: 'Quality/modality: cardinal (initiating), fixed (sustaining), or mutable (adapting). Always one of these three English literals, whatever the lang parameter says, so it stays safe to compare against in code. Use modalityLocalized for anything a reader sees.'
modalityLocalized:
type: string
example: Cardinal
description: Modality name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
rulingPlanet:
type: string
example: Mars
description: Traditional ruling planet that governs this sign. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use rulingPlanetLocalized for anything a reader sees.
rulingPlanetLocalized:
type: string
example: Marte
description: Ruling planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
dates:
type: object
properties:
start:
type: string
example: Mar 21
description: Start date of this sign season.
end:
type: string
example: Apr 19
description: End date of this sign season.
required:
- start
- end
description: Tropical zodiac date range for this sign.
keywords:
type: array
items:
type: string
example:
- ambitious
- courageous
- energetic
description: Key personality traits and descriptive words for this sign.
description:
type: object
properties:
short:
type: string
example: Ambitious, independent, impatient
description: Brief 1-2 sentence personality overview.
long:
type: string
example: Aries, the first sign in the zodiac, belongs to those born between March 21 and April 19. Aries are the trailblazers. Passionate and independent, an Aries will never do something just because everyone else is doing it. Competitive to the max, the best way to motivate an Aries is to turn something into a contest.
description: Detailed multi-paragraph sign profile with personality analysis.
required:
- short
- long
description: Sign description in short and long form.
famous:
type: array
items:
type: string
example:
- Leonardo da Vinci
- Lady Gaga
description: Notable people born under this zodiac sign.
strengths:
type: array
items:
type: string
example:
- You are the most courageous and ambitious sign, the leader of every pack.
- Your determination is unmatched when it comes to getting what you want.
- You work hard but also play hard, and you are the life of every party.
description: Key strengths and lovable qualities of this sign.
motto:
type: string
example: I am.
description: Signature motto or tagline for this sign.
gifts:
type: string
example: 'Whether it is backpacking around the world, launching a business, or training for a marathon, once an Aries sets a goal they will achieve it. Rams never need a plus one: they love their own company.'
description: Greatest gifts and natural talents of this sign.
challenges:
type: string
example: The world according to an Aries makes so much sense that they have a hard time accepting alternative viewpoints. Slowing down is also tough, and to maintain relationships an Aries must learn to adapt to other ways of doing and seeing.
description: Greatest challenges and growth areas for this sign.
weapon:
type: string
example: Strong, adamant, and forged in fire, it is fitting that the Aries secret weapon is iron, one of the strongest elements. Weld it, cast it, or temper it, and iron takes on a seemingly limitless range of shapes.
description: Secret weapon or superpower of this sign.
compatibleSigns:
type: array
items:
type: string
example:
- Leo
- Sagittarius
- Gemini
description: Most compatible zodiac signs for this sign. Trine partners (same element, 120 degrees apart) listed first, followed by a sextile partner (complementary element, 60 degrees apart). Use for compatibility widgets, dating app onboarding, sign profile cards, and zodiac matchmaking.
required:
- id
- name
- symbolName
- element
- modality
- rulingPlanet
- dates
- keywords
- description
- compatibleSigns
'400':
description: Validation error. `issues[]` lists every failed field.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: First issue summary.
code:
type: string
enum:
- validation_error
issues:
type: array
description: Every validation failure. Use this to rebuild a valid request.
items:
type: object
properties:
path:
type: string
description: Dot-separated field path, or "(root)" for top-level.
message:
type: string
code:
type: string
description: Zod issue code (invalid_type, too_small, too_big, invalid_string, ...).
expected:
type: string
description: Expected type for invalid_type.
minimum:
description: Minimum bound for too_small issues.
oneOf:
- type: number
- type: string
maximum:
description: Maximum bound for too_big issues.
oneOf:
- type: number
- type: string
inclusive:
type: boolean
format:
type: string
description: Format name for string issues (regex, email, url, uuid).
pattern:
type: string
description: Regex pattern when format is regex.
required:
- path
- message
required:
- error
- code
- issues
'401':
description: Invalid or missing API key
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'404':
description: Zodiac sign not found
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Resource not found
description: Human-readable error message. The wording may change, so do not parse it programmatically. Switch on the stable code instead.
code:
type: string
example: not_found
description: Machine-readable error code. Stable identifier for programmatic error handling.
required:
- error
- code
'405':
description: Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
headers:
Allow:
description: Comma-separated list of allowed methods (RFC 9110).
schema:
type: string
content:
application/json:
schema:
type: object
properties:
error:
type: string
code:
type: string
enum:
- method_not_allowed
allow:
type: array
items:
type: string
description: Allowed HTTP methods for this path. Mirrors the Allow response header.
docs:
type: string
description: Link to the product page for this domain.
required:
- error
- code
- allow
'429':
description: Monthly rate limit exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'500':
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
/astrology/planet-meanings:
get:
operationId: listPlanetMeanings
tags:
- Western Astrology
summary: Get all planet meanings - Complete astrology planet interpretations list
description: 'Returns all 14 astrological bodies (the 10 classical planets Sun through Pluto, the lunar nodes, Chiron, and Black Moon Lilith) with essential meanings: name, symbol, tagline, category (personal/social/generational), ruling sign, and short descriptions. Perfect for astrology reference apps, planet meaning widgets, birth chart interpretation tools, astrology learning platforms, planetary keywords reference, and zodiac planet guides. Use GET /planet-meanings/{id} for complete profiles with detailed interpretations, keywords, temperature, and dignities (rulership/detriment/exaltation/fall).'
security:
- apiKey: []
parameters:
- schema:
type: string
enum:
- en
- tr
- de
- es
- hi
- pt
- fr
- ru
- zh-Hans
- zh-Hant
default: en
example: en
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
required: false
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
name: lang
in: query
responses:
'200':
description: Successfully retrieved all 14 body meanings
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
example: sun
description: Lowercase planet identifier (e.g., sun, moon, mercury).
name:
type: string
example: Sun
description: Display name of the planet.
symbol:
type: string
example: ☉
description: Unicode astronomical symbol for this planet.
tagline:
type: string
example: Self-awareness and ego
description: Short tagline summarizing this planet in astrology.
category:
type: string
example: personal
description: 'Planet classification: personal (Sun-Mars), social (Jupiter-Saturn), or generational (Uranus-Pluto).'
rulership:
type: string
example: Leo
description: Zodiac sign this planet rules. The sign where the planet operates most naturally. Absent for the lunar nodes, Chiron, and Black Moon Lilith.
description:
type: string
example: The Sun represents your core identity, ego, and conscious will. It governs vitality, self-expression, and life purpose. Your Sun sign is the foundation of your natal chart.
description: Brief overview of the planet and its astrological significance.
required:
- id
- name
- symbol
- tagline
- description
description: All 14 astrological bodies with names, symbols, taglines, categories, and brief descriptions.
'400':
description: Validation error. `issues[]` lists every failed field.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: First issue summary.
code:
type: string
enum:
- validation_error
issues:
type: array
description: Every validation failure. Use this to rebuild a valid request.
items:
type: object
properties:
path:
type: string
description: Dot-separated field path, or "(root)" for top-level.
message:
type: string
code:
type: string
description: Zod issue code (invalid_type, too_small, too_big, invalid_string, ...).
expected:
type: string
description: Expected type for invalid_type.
minimum:
description: Minimum bound for too_small issues.
oneOf:
- type: number
- type: string
maximum:
description: Maximum bound for too_big issues.
oneOf:
- type: number
- type: string
inclusive:
type: boolean
format:
type: string
description: Format name for string issues (regex, email, url, uuid).
pattern:
type: string
description: Regex pattern when format is regex.
required:
- path
- message
required:
- error
- code
- issues
'401':
description: Invalid or missing API key
content:
application/json:
schema:
# --- truncated at 32 KB (782 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/roxyapi/refs/heads/main/openapi/roxyapi-western-astrology-api-openapi.yml