Vestraluna Pro · v1

API documentation

Personal horoscopes, compatibility and star maps computed from the real sky. Base URL https://vestraluna.com. JSON in, JSON (or SVG) out. Languages: en, it, fr, de.

Getting started

Sign in to the console with your Vestraluna account, add your site and set the domains allowed to embed the widgets. You get a public key (vl_pub_…, for widgets, bound to your domains) and a secret key (vl_live_…, for server-to-server calls). The key demo works everywhere with a watermark and low limits.

Authentication

Send the secret key in the x-vestraluna-key header (or ?key=). Never put the secret key in a web page: use the public key there; it is only accepted from your allowed domains.

curl https://vestraluna.com/api/pro/v1/horoscope?lang=en \
  -H "x-vestraluna-key: vl_live_…"

Embeds

One container, one script. The iframe resizes itself; the credit line stays in your page, outside the iframe.

<div data-vestraluna="sky" data-key="vl_pub_…" data-lang="en"
     data-accent="#c8102e" data-mode="day" data-font="serif"></div>
<p class="vl-credit">Personal sky by <a href="https://vestraluna.com/en/my-sky">Vestraluna</a></p>
<script src="https://vestraluna.com/pro/v1/embed.js" async></script>

Attribute	Values
`data-vestraluna`	`sky` · `horoscope` · `match` · `starmap`
`data-key`	your public key
`data-lang`	`en` · `it` · `fr` · `de`
`data-accent`, `data-mode`, `data-font`	override the brand saved in the console (`#hex`, `night\|day`, `serif\|sans`)
`data-cta`	Match only: URL of the final call to action (overrides the console setting)
`data-sign`	Horoscope only: show a single sign

Events: the container dispatches vestraluna:<name> DOM events. vestraluna:subscribe (Personal Sky, reader asked for the daily email, detail.birth), vestraluna:match (result shown), vestraluna:starmap (customer confirmed a sky: attach detail to the cart line item).

document.querySelector('[data-vestraluna="starmap"]')
  .addEventListener('vestraluna:starmap', (e) => addToCart({ properties: e.detail }));

Attribution

Every plan requires the visible credit line with its link to Vestraluna next to the widget, and in any page or email that shows API content. Every JSON response carries an attribution object (text, url) and a Link: <…>; rel="source" header; SVGs carry the credit inside the image.

Personal Sky

One reader's day: their birth chart against today's planets, ranked and explained, with the best window of the day. Computed per request, nothing stored, no AI call at request time.

`POST /api/pro/v1/personal`

The personal day for one reader. With format=email it also returns a ready-to-send, email-safe HTML block (600 px, your brand colours) and its plain-text version, ending with the credit line.

Parameter	Description
`birth`	object {date, time\|null, lat, lon, tz}. Or cityId (from /api/cities) + birthDate + birthTime.
`lang`	en · it · fr · de
`date`	optional, the reader's day (YYYY-MM-DD); default today
`tz`	optional, the reader's current time zone (IANA), for the best window
`format`	json (default) · email
`ctaUrl`	optional, https URL for the email button (e.g. your horoscope page)

curl -X POST https://vestraluna.com/api/pro/v1/personal \
  -H "x-vestraluna-key: vl_live_…" -H "content-type: application/json" \
  -d '{"birth":{"date":"1990-04-12","time":"08:30","lat":45.4642,"lon":9.19,"tz":"Europe/Rome"},"lang":"it","format":"email"}'

→ { "big3": {...}, "score": 4, "headline": "...", "summary": "...",
    "focus": {"love":4,"work":3,"energy":5,"mood":4},
    "transits": [{"title":"...","text":"...","tags":["love"]}, ...],
    "moon": {...}, "bestWindow": {"from":"14:10","to":"16:10"}, "lucky": {...},
    "tomorrow": "...", "email": {"html":"...","text":"..."},
    "attribution": {"text":"Cielo personale di Vestraluna","url":"https://vestraluna.com/it/il-mio-cielo?..."} }

Daily horoscope (12 signs)

The day's horoscope for the twelve signs, written natively in each language, with the calculated sky of the day and a source link per sign.

`GET /api/pro/v1/horoscope`

Twelve signs (or one) for a period. Trial and demo keys receive excerpts (textLevel: "excerpt"); Pro and Enterprise receive full texts. This protects both your pages and ours from duplicate content.

Parameter	Description
`lang`	en · it · fr · de
`period`	today (default) · tomorrow · week
`sign`	optional: aries … pisces
`date`	optional YYYY-MM-DD; 404 if that edition does not exist

curl "https://vestraluna.com/api/pro/v1/horoscope?lang=fr&period=today" -H "x-vestraluna-key: vl_live_…"

→ { "sky": {"moon":{...},"retrograde":[...]},
    "signs": [{"sign":"aries","name":"Bélier","stars":4,"headline":"...","excerpt":"...",
               "themes":{"love":{"stars":3,"excerpt":"..."}, ...},"source":"https://vestraluna.com/fr/horoscope/belier?..."}, ...],
    "textLevel": "excerpt", "attribution": {...} }

Match (synastry)

Compatibility of two people from their birth charts: an overall score, four dimensions, an archetype and the strongest aspects between the two charts. A birth date is enough; time and place add the Ascendant and tighter Moon aspects.

`POST /api/pro/v1/synastry`

Scores are calibrated on real distributions: across random pairs the mean is about 62, the middle 80% between 45 and 82.

Parameter	Description
`a, b`	objects {date, time?, lat?, lon?, tz?}; only date is required (years 1900–2030)
`lang`	en · it · fr · de
`names`	optional {a, b}, used in the texts

curl -X POST https://vestraluna.com/api/pro/v1/synastry \
  -H "x-vestraluna-key: vl_live_…" -H "content-type: application/json" \
  -d '{"a":{"date":"1992-07-03"},"b":{"date":"1990-11-21","time":"18:40","lat":48.85,"lon":2.35,"tz":"Europe/Paris"},"lang":"en"}'

→ { "score": 74, "archetype": {"id":"...","title":"Slow-burn magnetism","text":"..."},
    "dimensions": {"attraction":{"value":81,"verdict":"..."},"emotional":{...},"communication":{...},"stability":{...}},
    "aspects": [{"a":"venus","b":"mars","type":"trine","nature":"soft","orb":1.2,"text":"..."}, ...],
    "signs": {"a":"cancer","b":"scorpio","pair":{"title":"...","text":"...","url":"https://vestraluna.com/en/compatibility/cancer-scorpio?..."}},
    "elements": {...}, "attribution": {...} }

Star Map & chart wheel

Print-ready vector posters: the exact sky above a moment and place (stereographic, north up, refraction, real Moon phase and planets), and natal chart wheels. Fonts are embedded; every file carries a linked credit to vestraluna.com.

`GET /api/pro/v1/starmap`

SVG poster (or JSON metadata with format=json). Use the secret key server-side to fetch print files; the public key works from your allowed domains for previews.

Parameter	Description
`date`	YYYY-MM-DD (1800–2200), required
`time`	HH:MM local, optional (default 21:00, not printed)
`city \| lat, lon, tz`	a city id from /api/cities, or coordinates and an IANA time zone
`place`	optional label printed instead of the city name
`style`	midnight (default) · ivory · noir · aurora
`size`	a4 · a3 (default) · a2 · 30x40 · 50x70 · square · thumb
`title, subtitle`	up to 60 and 90 characters
`lines, planets, names, grid`	1/0 toggles (defaults 1, 1, 1, 0)
`lang`	en · it · fr · de (date format, compass letters, credit)
`format, download`	svg (default) · json; download=1 returns an attachment

curl "https://vestraluna.com/api/pro/v1/starmap?date=2019-06-14&time=22:30&lat=41.9&lon=12.5&tz=Europe/Rome&style=ivory&size=50x70&title=Our%20night&lang=it" \
  -H "x-vestraluna-key: vl_live_…" -o poster.svg

`GET /api/pro/v1/chart-wheel`

Natal chart wheel as SVG (signs, houses with AC/MC, planets, aspect lines). Same place, time, style, size, title and lang parameters. Without a time there are no houses and no Ascendant. format=json returns the full natal chart.

Parameter	Description
`(same as starmap)`	date, time, city \| lat/lon/tz, style, size, title, subtitle, lang, format

Limits & errors

Plan	Calls per day
demo	3,000 (shared)
Trial	1,000
Pro	50,000
Enterprise	by contract

401 invalid key · 403 product not enabled or domain not allowed · 429 daily quota reached · 400 invalid input (the body says which field). No birth data sent to the API or the widgets is stored.

Star data: d3-celestial (BSD-3). Planetary positions: astronomy-engine (MIT). Texts are written with AI under Vestraluna's astrological rules.