URL-conventies en gratis endpoints

Krijg je een 404 op een doodgewoon verzoek, dan is het waarschijnlijk een verkeerd prefix of zoek je Swagger UI op een niet-standaard pad. Deze pagina legt alle canonieke URL’s en aliassen vast.

Padprefix

Alle endpoints leven onder /v1/. Er zijn geen andere prefixen.

✅ https://api.astroway.info/v1/chart
✅ https://api.astroway.info/v1/health
❌ https://api.astroway.info/api/chart        - 404 (missing /v1/ prefix)
❌ https://api.astroway.info/api/v1/chart     - 404 (our internal path, not exposed)
❌ https://api.astroway.info/v1/v1/chart      - 308 redirect to /v1/chart (typical SDK base-URL bug fix)

Gebruik je per ongeluk /api/<endpoint>, dan geven we een 404 terug met het veld error.code = "WRONG_PREFIX" en een hint - je SDK kan dat afhandelen en het juiste pad voorstellen.

Dit is geen LLM-proxy

AstroWay is een API voor astrologische berekeningen, geen proxy voor LLM’s. Kom je met het muscle memory van de OpenAI SDK en probeer je gewoon base_url naar de onze te veranderen, dan werkt dat niet:

❌ POST /v1/chat/completions            - doesn't exist
❌ POST /v1/completions                 - doesn't exist
❌ GET  /v1/models                      - doesn't exist (deliberately)
❌ POST /v1/embeddings                  - doesn't exist

We publiceren de lijst met AI-providers om twee redenen niet:

Niet actionable voor de integrator. Je roept /v1/interpret/natal of /v1/horoscope/daily aan - onze server kiest zelf een LLM uit meerdere providers met automatische fallback. Een andere provider verandert de shape van de response niet, alleen de latency en af en toe de formulering.
Operationele vrijheid. De keten verandert zonder aankondiging (HuggingFace eruit op 2026-05-18, NIM/ZAI erbij). Als we een concrete models[] zouden aankondigen, werd dat de facto een contract.

AI is alleen een implementation detail in /v1/interpret/* (geboortehoroscoop, synastrie, transits), /v1/horoscope/* (dag- en weekhoroscoop), /v1/dev-assistant (documentatie-assistent) en /v1/reports/* (PDF-verhalen). De overige 750+ endpoints zijn deterministische Swiss Ephemeris zonder AI.

OpenAPI 3.1-specificatie

Het canonieke adres is /v1/openapi.json. Voor het gemak van integraties zijn er aliassen:

Alias	Waarheen	Waarom die bestaat
`/v1/swagger.json`	301 → `/v1/openapi.json`	Swagger 2.0 / openapi-generator-conventie
`/v1/api-docs/swagger.json`	301 → `/v1/openapi.json`	springdoc-standaard
`/v1/v3/api-docs`	301 → `/v1/openapi.json`	Spring Boot 3
`/v1/v2/api-docs`	301 → `/v1/openapi.json`	Spring Boot 2
`/v1/swagger/v1/swagger.json`	301 → `/v1/openapi.json`	ASP.NET Core
`/v1/swagger`, `/v1/swagger-ui`, `/v1/swagger-ui.html`	302 → `/v1/docs`	Swagger UI-host

Interactieve Swagger UI is beschikbaar op /v1/docs (ook gespiegeld in de browserdocumentatie op /docs/api/).

Gratis systeemendpoints

Deze paden hebben geen API-sleutel nodig en schrijven geen credits af - je kunt ze aanroepen vanuit elke frontend, monitoring of health-check.

Pad	Wat het teruggeeft
`GET /v1/health`	`{status, version, uptime_seconds, timestamp}` - snelle liveness probe
`GET /v1/health/deep`	Bereikbaarheidscontrole per database (voor UptimeRobot / Pingdom), 503 als ten minste één database onbereikbaar is
`GET /v1/version`	`{version, build_commit, started_at, uptime_seconds, docs_url}` - gedetailleerde self-check voor SDK’s
`GET /v1/openapi.json`	Volledige OpenAPI 3.1-specificatie met voorbeelden + `x-codeSamples`
`GET /v1/docs`	Interactieve Swagger UI
`GET /v1/reference/*`	Canonieke naslagtabellen (tekens, planeten, huizen, aspecten) - IP-rate-limit, zonder sleutel
`GET /v1/i18n/langs`, `GET /v1/i18n/dict/:lang`	Lijst met talen en UI-woordenboeken - voor widgets

Gratis endpoints waarvoor je je moet registreren

Accountendpoints zijn alleen met een JWT-token beschikbaar (uitgegeven bij het inloggen), maar ze schrijven geen credits af van het saldo van je plan.

Prefix	Wat het is
`/v1/auth/*`	Registratie, inloggen, refresh, password reset
`/v1/me`, `/v1/me/*`	Profiel, statistieken, recent calls
`/v1/keys`, `/v1/keys/*`	Beheer van API-sleutels
`/v1/admin/*`	Beheerpaneel (vereist `api_role = admin`)
`/v1/messages`	Feedback vanuit de widget (anoniem, rate-limit)
`/v1/dev-assistant`, `/v1/dev-assistant/stream`	AI-assistent voor de documentatie (anoniem, eigen limiet)
`/v1/widget-config`	Runtime feature-flags voor de widget
`/v1/embed/*`	Embeddable iframe-widgets (IP-rate-limit)
`/v1/oauth/*`	Google / GitHub-login
`/v1/books/*`	Birth Book - aparte scope-JWT (uitgegeven door een WordPress mu-plugin)

Betaalde berekeningsendpoints

Alle astrologische berekeningen schrijven credits af van je plan. De exacte kosten van elk staan op de pagina Kosten per endpoint. Kort samengevat:

Tier	Credits	Voorbeelden
0	0	`/v1/reference/*` - openbare naslagtabellen, zonder sleutel
½	5	`/v1/kabbalah/sephiroth`, `/v1/fixed-stars/catalog` - statische tabellen
1	10	`/v1/planets`, `/v1/sun-times`, `/v1/moon-phase`
2	20	`/v1/chart`, `/v1/harmonics`, `/v1/horary`
3	50	`/v1/synastry`, `/v1/progressions`, `/v1/acg`
4	100	`/v1/transit-calendar`, `/v1/group-synastry`
5	250	`/v1/rectification/trutine`, AI-verhalen `/v1/reports/ai/*`
6	500	`/v1/rectification`
7	5000	PDF-rapporten: `/v1/reports/natal`, `/v1/reports/synastry`

Cachekortingen: X-Cache: HIT (5-minuten idempotency-cache) - 0 credits. AI-endpoints (/interpret/*) - 50% korting bij een cache hit.

Responseheaders bevatten X-Credits-Used, X-Credits-Remaining, X-Credits-Limit - SDK’s kunnen het saldo automatisch bijhouden.

Taal van de responses

De taal stel je in via ?lang= of de header Accept-Language. Er worden 21 talen ondersteund.

Velden uit gesloten verzamelingen (tekens, planeten, weekdagen, maanfasen, de Human Design-woordenschat, namen van de Grote Arcana van de Tarot) komen twee keer terug: de Engelse identifier blijft op zijn plek als stabiel contract, en ernaast komt een object localized met de vertaling:

{
  "phaseName": "Waxing Gibbous",
  "moonSign": "Capricorn",
  "localized": { "phaseName": "Zunehmender Mond", "moonSign": "Steinbock", "sunSign": "Löwe" }
}

Vergelijk op de Engelse waarden, toon localized. Deze namen komen uit een expliciete termentabel in de code, niet uit machinevertaling: terminologie kun je niet woord voor woord vertalen, anders wordt een maanfase een financieel begrip.

In Human Design hebben de centra in localized.centers als sleutels dezelfde identifiers als centers[].name, dus je koppelt op sleutel, niet op de vertaalde string. In de Tarot doet localized.cards hetzelfde, met de slug van de kaart als sleutel.

Velden uit open verzamelingen zijn voorlopig Engels en als zodanig gedocumenteerd: themes[] bij de planeet van de dag, trefwoorden en betekenissen van Tarotkaarten, namen van kanalen en poorten in Human Design. De namen van de Kleine Arcana worden opgebouwd uit bevroren vormen van rang en kleur, dus het hele deck van 78 kaarten is gelokaliseerd en nameLocalized is daarvoor true; het veld blijft alleen false waar de tabel geen naam kan geven. Open verzamelingen vertaal je aan je eigen kant of je wacht op aparte woordenboeken.

Compacte response: `fields` en `precision`

Een agent betaalt voor elk token dat hij leest. POST /v1/chart geeft ongeveer 32 KB terug, terwijl het model er meestal twee kolommen van nodig heeft, en elke lengte komt met veertien decimalen waar niemand nauwkeuriger rekent dan op een boogminuut.

Twee queryparameters lossen dit op in de laatste stap, dus ze werken op alle endpoints:

fields - een kommagescheiden lijst van paden, relatief aan data. Een pad wordt toegepast op elk element van een array, dus planets.name betekent de naam van elke planeet, niet een sleutel van de array.
precision - een geheel getal van 0 tot 15, rondt alle niet-gehele getallen in de response af. Gehele getallen blijven ongemoeid: een identifier is geen meting.

curl -X POST "https://api.astroway.info/v1/chart?fields=planets.name,planets.longitude&precision=2" \
  -H "X-Api-Key: aw_live_..." -H "Content-Type: application/json" \
  -d '{"date":"1990-05-15","time":"14:30:00","timezone":"Europe/Kyiv","latitude":50.45,"longitude":30.52}'

Dit paar parameters levert bij een geboortehoroscoop 511 bytes in plaats van 32 410 op, dus een response die zestig keer kleiner is.

Een pad dat niets vond, verdwijnt niet stilletjes. Het komt terug in het veld _fields_unmatched naast de response: een deel van de velden is echt optioneel en ontbreekt in een bepaalde response, dus het is geen fout. Maar een lijst waarin geen enkel pad overeenkwam is een typefout, en die geeft 400 FIELDS_UNKNOWN terug met de opsomming. Een leeg object in plaats van een horoscoop zou een zelfverzekerd fout antwoord zijn.

Beide parameters gaan in de query, niet in een header, en dat is bewust: de responsecache gebruikt als sleutel de methode, het pad, de body, de gesorteerde query en het plan. Een modus in een header zou het incident van 2026-08-22 herhalen, toen Accept-Language niet in de sleutel zat en een Duitse response aan de volgende werd gegeven als Oekraïense.

De shaping geldt alleen voor data. De envelop, _footer en _warning blijven heel.

Hetzelfde werkt via MCP. Elke tool op mcp.astroway.info accepteert fields en precision naast zijn eigen parameters en geeft ze aan de API door in dezelfde query. Een geboortehoroscoop via MCP woog 91 737 bytes, omdat de data twee keer kwam: als tekstblok met inspringing en als gestructureerd veld. Met dezelfde drie paden en precision: 2 is dat 1 182 bytes.

Aanroep geboortehoroscoop	Bytes
MCP, zoals vóór 21.09.2026	91 737
MCP, zonder inspringing in het tekstblok	72 484
MCP, `precision: 2`	61 356
MCP, drie paden in `fields` plus `precision: 2`	1 182
REST, drie paden in `fields` plus `precision=2`	559

Onbekende geboortetijd

Een flink deel van de eindgebruikers kent zijn exacte geboortetijd niet. Vul je dan een fictief middaguur in en bereken je de horoscoop zoals gewoonlijk, dan bevat de response een ascendant en huiscuspen die betrouwbaar lijken, maar er ongeveer een teken naast zitten voor elke twee uur afwijking.

Daarom kun je in plaats van time ook timeUnknown: true meesturen:

curl -X POST https://api.astroway.info/v1/chart \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-03-15","timeUnknown":true,"timezoneOffset":2,"latitude":50.45,"longitude":30.52}'

Wat de API in deze modus teruggeeft:

Veld	Waarde
`planets`	berekend voor lokaal middaguur
`aspects`	berekend, maar aspecten met de Maan zijn onbetrouwbaar (zie hieronder)
`houses`	`null`
`houseAspects`	`null`
`chartSect`	`null`
`siderealTime`	`null`
`timeUnknown`	een blok met uitleg: wat er precies is weggelaten en waar de Maan kan staan

Het blok timeUnknown.moon bevat de lengte van de Maan aan het begin en einde van de dag, de boog die ze in die dag aflegt (11.8-15.4°), de lijst met tekens waarin ze stond en de vlag changesSign. De Maan kan binnen een dag van teken wisselen, dus dit bereik kun je beter aan de gebruiker tonen dan verbergen achter één getal.

De vlag wordt geaccepteerd door /v1/chart en /v1/synastry (in synastrie kun je hem per partner apart zetten). De overige endpoints zijn afhankelijk van huizen of hoeken en antwoorden met 400 TIME_UNKNOWN_UNSUPPORTED: een expliciete fout is beter dan een stilletjes genegeerde vlag en een verzonnen ascendant in de response.

Versiebeheer van de API

Major-versie in de URL (/v1/). Breaking changes komen alleen met /v2/, niet in-place. Details: Versiebeheer.

GET /v1/version geeft de huidige deploy terug:

curl https://api.astroway.info/v1/version
# {
#   "version": "2.71.0",
#   "build_commit": "abc1234",
#   "started_at": "2026-05-27T10:42:00Z",
#   "uptime_seconds": 12345,
#   "docs_url": "https://api.astroway.info/docs/api/"
# }

SDK’s kunnen dit bij het opstarten aanroepen om te debuggen “waarom gedraagt het zich ineens anders” - het veld build_commit identificeert de deploy exact.

Foutieve aanroepen die we het vaakst zien

Uit een analyse van productielogs over 90 dagen, 5 typische integratorfouten:

/api/<endpoint> in plaats van /v1/<endpoint>: een gewoonte uit WordPress wp-json. Nu geven we een JSON 404 met een hint terug.
/v1/v1/<endpoint>: de SDK is geconfigureerd met baseUrl = .../v1 en zet er nog eens /v1/X achter. Nu een 308 redirect.
/swagger.json in plaats van /v1/openapi.json: auto-probe van Postman/Insomnia. Nu een 301 redirect.
/v1/me, /v1/auth/keys/me zonder Authorization: Bearer <jwt> → 401. Controleer of het token in de header wordt meegestuurd.
/v1/embed/natal met een API-sleutel in plaats van een embed-token → 401. Embed-endpoints accepteren een openbaar embed-token uit het dashboard, geen API-sleutel.