URL-Konventionen und kostenlose Endpunkte

Wenn du bei einer gewöhnlichen Anfrage ein 404 siehst, ist höchstwahrscheinlich das Präfix falsch oder du suchst die Swagger UI unter einem nicht standardmäßigen Pfad. Diese Seite hält alle kanonischen URLs und Aliase fest.

Pfadpräfix

Alle Endpunkte liegen unter /v1/. Andere Präfixe gibt es nicht.

✅ 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)

Wenn du versehentlich /api/<endpoint> verwendet hast, geben wir 404 mit dem Feld error.code = "WRONG_PREFIX" und einem Hinweis zurück - dein SDK kann das verarbeiten und den richtigen Pfad vorschlagen.

Das ist kein LLM-Proxy

AstroWay ist eine API für astrologische Berechnungen, kein Proxy für LLMs. Wenn du mit dem Muskelgedächtnis des OpenAI SDK kommst und einfach base_url auf unsere Adresse änderst, funktioniert das nicht:

❌ 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

Wir veröffentlichen die Liste der AI-Anbieter aus zwei Gründen nicht:

Für Integratoren nicht handlungsrelevant. Du rufst /v1/interpret/natal oder /v1/horoscope/daily auf - unser Server wählt das LLM selbst aus mehreren Anbietern mit automatischem Fallback. Ein Anbieterwechsel ändert nicht die Form der Antwort, nur die Latenz und gelegentlich die Formulierung.
Operative Freiheit. Die Kette ändert sich ohne Vorankündigung (Ausschluss von HuggingFace am 2026-05-18, Aufnahme von NIM/ZAI). Würden wir konkrete models[] ankündigen, würde das de facto zum Vertrag.

AI ist nur ein Implementierungsdetail in /v1/interpret/* (Geburtshoroskop, Synastrie, Transite), /v1/horoscope/* (Tages- und Wochenhoroskop), /v1/dev-assistant (Assistent für die Dokumentation) und /v1/reports/* (PDF-Narrative). Die übrigen 750+ Endpunkte sind deterministisches Swiss Ephemeris ohne AI.

OpenAPI-3.1-Spezifikation

Die kanonische Adresse ist /v1/openapi.json. Zur Bequemlichkeit bei Integrationen gibt es Aliase:

Alias	Ziel	Warum es ihn gibt
`/v1/swagger.json`	301 → `/v1/openapi.json`	Konvention von Swagger 2.0 / openapi-generator
`/v1/api-docs/swagger.json`	301 → `/v1/openapi.json`	Standard von springdoc
`/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`	Host der Swagger UI

Die interaktive Swagger UI ist unter /v1/docs erreichbar (außerdem gespiegelt in der Browser-Dokumentation unter /docs/api/).

Kostenlose Systemendpunkte

Diese Pfade benötigen keinen API-Schlüssel und buchen keine Credits ab - sie können aus jedem Frontend, Monitoring oder Health-Check aufgerufen werden.

Pfad	Was er zurückgibt
`GET /v1/health`	`{status, version, uptime_seconds, timestamp}` - schneller Liveness-Probe
`GET /v1/health/deep`	Erreichbarkeitsprüfung pro Datenbank (für UptimeRobot / Pingdom), 503, wenn mindestens eine Datenbank nicht erreichbar ist
`GET /v1/version`	`{version, build_commit, started_at, uptime_seconds, docs_url}` - detaillierter Self-Check für SDKs
`GET /v1/openapi.json`	Vollständige OpenAPI-3.1-Spezifikation mit Beispielen + `x-codeSamples`
`GET /v1/docs`	Interaktive Swagger UI
`GET /v1/reference/*`	Kanonische Verzeichnisse (Zeichen, Planeten, Häuser, Aspekte) - IP-Rate-Limit, ohne Schlüssel
`GET /v1/i18n/langs`, `GET /v1/i18n/dict/:lang`	Liste der Sprachen und UI-Wörterbücher - für Widgets

Kostenlose Endpunkte, die eine Registrierung erfordern

Kontoendpunkte sind nur mit einem JWT-Token erreichbar (wird beim Login ausgegeben), buchen aber keine Credits vom Planguthaben ab.

Präfix	Was es ist
`/v1/auth/*`	Registrierung, Login, Refresh, Passwort-Reset
`/v1/me`, `/v1/me/*`	Profil, Statistik, letzte Aufrufe
`/v1/keys`, `/v1/keys/*`	Verwaltung der API-Schlüssel
`/v1/admin/*`	Admin-Bereich (erfordert `api_role = admin`)
`/v1/messages`	Feedback aus dem Widget (anonym, Rate-Limit)
`/v1/dev-assistant`, `/v1/dev-assistant/stream`	AI-Assistent für die Dokumentation (anonym, eigenes Limit)
`/v1/widget-config`	Runtime-Feature-Flags für das Widget
`/v1/embed/*`	Einbettbare iframe-Widgets (IP-Rate-Limit)
`/v1/oauth/*`	Login mit Google / GitHub
`/v1/books/*`	Birth Book - eigenes Scope-JWT (ausgegeben vom WordPress mu-plugin)

Kostenpflichtige Berechnungsendpunkte

Alle astrologischen Berechnungen buchen Credits von deinem Tarifplan ab. Die genauen Kosten jedes Endpunkts stehen auf der Seite Kosten der Endpunkte. Kurz gefasst:

Stufe	Credits	Beispiele
0	0	`/v1/reference/*` - öffentliche Verzeichnisse, ohne Schlüssel
½	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-Narrative `/v1/reports/ai/*`
6	500	`/v1/rectification`
7	5000	PDF-Berichte: `/v1/reports/natal`, `/v1/reports/synastry`

Cache-Rabatte: X-Cache: HIT (5-minütiger Idempotency-Cache) - 0 Credits. AI-Endpunkte (/interpret/*) - 50% Rabatt bei einem Cache-Hit.

Die Antwort-Header enthalten X-Credits-Used, X-Credits-Remaining, X-Credits-Limit - SDKs können das Guthaben automatisch verfolgen.

Sprache der Antworten

Die Sprache wird über ?lang= oder den Header Accept-Language festgelegt. Unterstützt werden 21 Sprachen.

Felder aus geschlossenen Mengen (Zeichen, Planeten, Wochentage, Mondphasen, das Vokabular von Human Design, die Namen der Großen Arkana im Tarot) kommen doppelt zurück: Der englische Bezeichner bleibt als stabiler Vertrag an seinem Platz, und daneben kommt ein Objekt localized mit der Übersetzung:

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

Vergleiche die englischen Werte, zeige localized an. Diese Namen stammen aus einer expliziten Terminologietabelle im Code, nicht aus maschineller Übersetzung: Fachbegriffe lassen sich nicht wörtlich übersetzen, sonst wird aus einer Mondphase ein Begriff aus der Finanzwelt.

In Human Design sind die Zentren in localized.centers mit denselben Bezeichnern verschlüsselt wie centers[].name, die Zuordnung erfolgt also über den Schlüssel und nicht über den übersetzten String. Im Tarot leistet localized.cards dasselbe, der Schlüssel ist der slug der Karte.

Felder aus offenen Mengen sind vorerst englisch und als solche dokumentiert: themes[] beim Planeten des Tages, Schlüsselwörter und Bedeutungen der Tarotkarten, Namen der Kanäle und Tore in Human Design. Die Namen der Kleinen Arkana werden aus festen Formen von Rang und Farbe zusammengesetzt, daher ist das gesamte Deck mit 78 Karten lokalisiert und nameLocalized ist dafür true; das Feld bleibt nur dort false, wo die Tabelle keinen Namen liefern kann. Offene Mengen übersetzt du auf deiner Seite oder wartest auf eigene Wörterbücher.

Kompakte Antwort: `fields` und `precision`

Ein Agent bezahlt für jedes Token, das er liest. POST /v1/chart liefert etwa 32 KB, das Modell braucht davon meist zwei Spalten, und jede Länge kommt mit vierzehn Nachkommastellen, wo niemand genauer als auf eine Bogenminute rechnet.

Zwei Anfrageparameter lösen das im letzten Schritt und funktionieren deshalb auf allen Endpunkten:

fields - eine kommagetrennte Liste von Pfaden, relativ zu data. Ein Pfad wird auf jedes Element eines Arrays angewendet, planets.name bedeutet also den Namen jedes Planeten und nicht einen Schlüssel des Arrays.
precision - eine ganze Zahl von 0 bis 15, rundet alle nicht ganzzahligen Zahlen in der Antwort. Ganze Zahlen bleiben unangetastet: Ein Bezeichner ist keine Messgröße.

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}'

Dieses Parameterpaar ergibt beim Geburtshoroskop 511 Bytes statt 32 410, die Antwort ist also sechzigmal kleiner.

Ein Pfad, der nichts gefunden hat, verschwindet nicht stillschweigend. Er kommt im Feld _fields_unmatched neben der Antwort zurück: Ein Teil der Felder ist tatsächlich optional und fehlt in einer konkreten Antwort, daher ist das kein Fehler. Eine Liste, in der kein einziger Pfad passt, ist dagegen ein Tippfehler und liefert 400 FIELDS_UNKNOWN mit Aufzählung. Ein leeres Objekt statt des Horoskops wäre eine selbstsichere falsche Antwort.

Beide Parameter gehen in die Query und nicht in einen Header, und das ist Absicht: Der Antwort-Cache wird nach Methode, Pfad, Body, sortierter Query und Plan verschlüsselt. Ein Modus im Header würde den Vorfall vom 2026-08-22 wiederholen, als Accept-Language nicht Teil des Schlüssels war und eine deutsche Antwort dem Nächsten als ukrainische ausgeliefert wurde.

Die Formung betrifft nur data. Der Envelope, _footer und _warning bleiben vollständig.

Dasselbe funktioniert über MCP. Jedes Tool auf mcp.astroway.info akzeptiert fields und precision neben seinen eigenen Parametern und gibt sie in derselben Query an die API weiter. Ein Geburtshoroskop über MCP wog 91 737 Bytes, weil die Daten doppelt kamen: als eingerückter Textblock und als strukturiertes Feld. Mit denselben drei Pfaden und precision: 2 sind es 1 182 Bytes.

Aufruf eines Geburtshoroskops	Bytes
MCP, wie vor dem 21.09.2026	91 737
MCP, ohne Einrückung im Textblock	72 484
MCP, `precision: 2`	61 356
MCP, drei Pfade in `fields` plus `precision: 2`	1 182
REST, drei Pfade in `fields` plus `precision=2`	559

Unbekannte Geburtszeit

Ein erheblicher Teil der Endnutzer kennt die genaue Geburtszeit nicht. Setzt man pauschal Mittag ein und berechnet das Horoskop wie gewohnt, erscheinen in der Antwort ein Aszendent und Häuserspitzen, die glaubwürdig aussehen, aber pro zwei Stunden Abweichung um etwa ein Zeichen danebenliegen.

Deshalb kannst du statt time den Wert timeUnknown: true übergeben:

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}'

Was die API in diesem Modus zurückgibt:

Feld	Wert
`planets`	berechnet für den lokalen Mittag
`aspects`	berechnet, aber Aspekte mit dem Mond sind unzuverlässig (siehe unten)
`houses`	`null`
`houseAspects`	`null`
`chartSect`	`null`
`siderealTime`	`null`
`timeUnknown`	ein Block mit Erklärung: was genau ausgelassen wurde und wo der Mond stehen kann

Der Block timeUnknown.moon enthält die Länge des Mondes zu Beginn und Ende des Tages, den im Laufe des Tages zurückgelegten Bogen (11.8-15.4°), die Liste der Zeichen, in denen er stand, und das Flag changesSign. Der Mond kann innerhalb eines Tages das Zeichen wechseln, daher solltest du diesen Bereich dem Nutzer zeigen, statt ihn hinter einer einzigen Zahl zu verstecken.

Das Flag akzeptieren /v1/chart und /v1/synastry (in der Synastrie kann es für jeden der Partner einzeln gesetzt werden). Die übrigen Endpunkte hängen von Häusern oder Achsen ab und antworten mit 400 TIME_UNKNOWN_UNSUPPORTED: Ein expliziter Fehler ist besser als ein stillschweigend ignoriertes Flag und ein erfundener Aszendent in der Antwort.

API-Versionierung

Major-Version in der URL (/v1/). Breaking Changes kommen nur mit /v2/, nicht in-place. Details unter Versionierung.

GET /v1/version gibt das aktuelle Deployment zurück:

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/"
# }

SDKs können das beim Start zum Debuggen von “warum verhält es sich plötzlich anders” aufrufen - das Feld build_commit identifiziert das Deployment eindeutig.

Fehlerhafte Aufrufe, die wir am häufigsten sehen

Aus der Analyse der Produktionslogs über 90 Tage, 5 typische Integratorfehler:

/api/<endpoint> statt /v1/<endpoint>: eine Gewohnheit aus WordPress wp-json. Jetzt geben wir ein JSON-404 mit Hinweis zurück.
/v1/v1/<endpoint>: Das SDK ist mit baseUrl = .../v1 konfiguriert und hängt /v1/X noch einmal an. Jetzt ein 308-Redirect.
/swagger.json statt /v1/openapi.json: Auto-Probe von Postman/Insomnia. Jetzt ein 301-Redirect.
/v1/me, /v1/auth/keys/me ohne Authorization: Bearer <jwt> → 401. Prüfe, ob das Token im Header übergeben wird.
/v1/embed/natal mit einem API-Schlüssel statt eines Embed-Tokens → 401. Embed-Endpunkte akzeptieren ein öffentliches Embed-Token aus dem Dashboard, keinen API-Schlüssel.