URL の規約と無料エンドポイント

よくあるリクエストで 404 が返る場合、原因はたいていプレフィックスの誤りか、標準的でないパスで Swagger UI を探していることです。このページでは、正規の URL とエイリアスをすべてまとめています。

パスのプレフィックス

すべてのエンドポイントは /v1/ の下にあります。 それ以外のプレフィックスはありません。

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

誤って /api/<endpoint> を使った場合は、error.code = "WRONG_PREFIX" フィールドとヒント付きの 404 を返します。SDK 側でこれを処理して、正しいパスを案内できます。

LLM プロキシではありません

AstroWay は 占星術計算の API であり、LLM のプロキシではありません。OpenAI SDK の手癖で base_url をこちらに変えるだけで済ませようとしても、うまくいきません。

❌ 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

AI プロバイダーの一覧は、2 つの理由で公開していません。

インテグレーターにとって実用的な情報ではありません。 あなたが呼び出すのは /v1/interpret/natal や /v1/horoscope/daily で、どの LLM を使うかは、自動フォールバック付きの複数プロバイダーからサーバーが選びます。プロバイダーが変わってもレスポンスの形は変わらず、変わるのはレイテンシとまれな言い回しの違いだけです。
運用上の自由度。 チェーンは予告なく変わります (2026-05-18 の HuggingFace の除外、NIM/ZAI の追加など)。具体的な models[] を公表すれば、それが事実上の契約になってしまいます。

AI は実装の詳細としてのみ存在します。 対象は /v1/interpret/* (出生図、シナストリー、トランジット)、/v1/horoscope/* (日次・週次のホロスコープ)、/v1/dev-assistant (ドキュメントのアシスタント)、/v1/reports/* (PDF の文章) です。残りの 750 以上 のエンドポイントは、AI を使わない決定論的な Swiss Ephemeris です。

OpenAPI 3.1 仕様

正規のアドレスは /v1/openapi.json です。連携の利便性のため、エイリアスを用意しています。

エイリアス	転送先	存在理由
`/v1/swagger.json`	301 → `/v1/openapi.json`	Swagger 2.0 / openapi-generator の慣習
`/v1/api-docs/swagger.json`	301 → `/v1/openapi.json`	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`	Swagger UI のホスト

インタラクティブな Swagger UI は /v1/docs で利用できます (ブラウザ向けドキュメント /docs/api/ にも同じ内容があります)。

無料のシステムエンドポイント

これらのパスは API キーが不要で、クレジットも消費しません。どのフロントエンド、監視、ヘルスチェックからでも呼び出せます。

パス	返す内容
`GET /v1/health`	`{status, version, uptime_seconds, timestamp}`、高速な liveness probe
`GET /v1/health/deep`	DB ごとの到達性チェック (UptimeRobot / Pingdom 向け)。DB が 1 つでも利用できなければ 503
`GET /v1/version`	`{version, build_commit, started_at, uptime_seconds, docs_url}`、SDK 向けの詳細なセルフチェック
`GET /v1/openapi.json`	例と `x-codeSamples` を含む完全な OpenAPI 3.1 仕様
`GET /v1/docs`	インタラクティブな Swagger UI
`GET /v1/reference/*`	正規のリファレンス (サイン、惑星、ハウス、アスペクト)。IP 単位のレート制限、キー不要
`GET /v1/i18n/langs`, `GET /v1/i18n/dict/:lang`	言語の一覧と UI 辞書、ウィジェット向け

登録が必要な無料エンドポイント

アカウント系のエンドポイントは JWT トークン (ログイン時に発行) がある場合のみ 利用できますが、プランの残高から クレジットは消費しません。

プレフィックス	内容
`/v1/auth/*`	登録、ログイン、refresh、パスワードリセット
`/v1/me`, `/v1/me/*`	プロフィール、統計、最近の呼び出し
`/v1/keys`, `/v1/keys/*`	API キーの管理
`/v1/admin/*`	管理パネル (`api_role = admin` が必要)
`/v1/messages`	ウィジェットからのフィードバック (匿名、レート制限あり)
`/v1/dev-assistant`, `/v1/dev-assistant/stream`	ドキュメントの AI アシスタント (匿名、個別の制限)
`/v1/widget-config`	ウィジェット用のランタイム feature flag
`/v1/embed/*`	埋め込み可能な iframe ウィジェット (IP 単位のレート制限)
`/v1/oauth/*`	Google / GitHub ログイン
`/v1/books/*`	Birth Book、専用のスコープ付き JWT (WordPress の mu-plugin が発行)

有料の計算エンドポイント

すべての 占星術の計算 は、料金プランからクレジットを消費します。各エンドポイントの正確なコストはエンドポイントごとのコストのページにあります。概要は次のとおりです。

Tier	クレジット	例
0	0	`/v1/reference/*`、公開リファレンス、キー不要
½	5	`/v1/kabbalah/sephiroth`, `/v1/fixed-stars/catalog`、静的なテーブル
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 の文章 `/v1/reports/ai/*`
6	500	`/v1/rectification`
7	5000	PDF レポート: `/v1/reports/natal`, `/v1/reports/synastry`

キャッシュ割引: X-Cache: HIT (5 分間のべき等性キャッシュ) は 0 クレジットです。AI エンドポイント (/interpret/*) はキャッシュヒット時に 50% 割引になります。

レスポンスヘッダー には X-Credits-Used、X-Credits-Remaining、X-Credits-Limit が含まれ、SDK は残高を自動で追跡できます。

レスポンスの言語

言語は ?lang= または Accept-Language ヘッダーで指定します。21 言語に対応しています。

閉じた集合 のフィールド (サイン、惑星、曜日、月の位相、Human Design の用語、タロットの大アルカナの名前) は 2 回返されます。英語の識別子は安定した契約として元の位置に残り、その隣に翻訳を含む localized オブジェクトが付きます。

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

比較には英語の値を使い、表示には localized を使ってください。これらの名前は機械翻訳ではなく、コード内の明示的な用語表から取られています。用語は逐語訳できません。そうしないと月の位相が金融用語になってしまいます。

Human Design では、localized.centers のセンターは centers[].name と同じ識別子をキーに持つため、翻訳された文字列ではなくキーで対応付けます。タロットでは localized.cards が同じ役割を果たし、キーはカードの slug です。

開いた集合 のフィールドは今のところ英語で、そのように文書化されています。今日の惑星の themes[]、タロットカードのキーワードと意味、Human Design のチャネルとゲートの名前です。小アルカナの名前はランクとスートの固定形から組み立てられるため、78 枚のデッキ全体がローカライズされ、nameLocalized は true になります。このフィールドが false のまま残るのは、表から名前を作れない場合だけです。開いた集合はご自身の側で翻訳するか、個別の辞書の提供をお待ちください。

コンパクトなレスポンス: `fields` と `precision`

エージェントは読むトークンごとに支払います。POST /v1/chart は約 32 KB を返しますが、モデルに必要なのはたいていそのうち 2 列だけです。しかも、誰も角度の 1 分より細かく扱わないのに、黄経はどれも小数点以下 14 桁で届きます。

2 つのクエリパラメータが最後の段階でこれを解決するため、すべてのエンドポイントで機能します。

fields: data からの相対パスをカンマ区切りで並べたものです。パスは配列の各要素に適用されるため、planets.name は配列のキーではなく各惑星の名前を意味します。
precision: 0 から 15 までの整数で、レスポンス中の整数でない数値をすべて丸めます。整数には触れません。識別子は測定値ではないからです。

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

この 2 つのパラメータで、出生図は 32 410 バイトではなく 511 バイト になります。レスポンスは 60 分の 1 です。

何も見つからなかったパスは黙って消えません。 レスポンスの隣の _fields_unmatched フィールドで返されます。一部のフィールドは本当に任意で、特定のレスポンスには存在しないため、これはエラーではありません。一方、1 つも パスが一致しなかった一覧はタイプミスであり、一覧付きの 400 FIELDS_UNKNOWN を返します。チャートの代わりに空のオブジェクトを返せば、自信たっぷりの誤答になってしまいます。

どちらのパラメータもヘッダーではなくクエリで渡すのは意図的です。レスポンスのキャッシュは、メソッド、パス、ボディ、ソート済みのクエリ、プランをキーにしています。ヘッダーでモードを指定すると 2026-08-22 のインシデントの再現になります。このときは Accept-Language がキーに含まれておらず、ドイツ語のレスポンスが次のリクエストにウクライナ語として返されました。

整形の対象は data だけです。エンベロープ、_footer、_warning はそのまま残ります。

MCP 経由でも同じように動作します。 mcp.astroway.info のすべてのツールは、固有のパラメータに加えて fields と precision を受け付け、同じクエリで API に渡します。MCP 経由の出生図は 91 737 バイトありました。データがインデント付きのテキストブロックと構造化フィールドの 2 回で届いていたためです。同じ 3 つのパスと precision: 2 を使うと 1 182 バイトになります。

出生図の呼び出し	バイト数
MCP、2026-09-21 以前	91 737
MCP、テキストブロックのインデントなし	72 484
MCP、`precision: 2`	61 356
MCP、`fields` に 3 つのパスと `precision: 2`	1 182
REST、`fields` に 3 つのパスと `precision=2`	559

出生時刻が不明な場合

エンドユーザーの多くは正確な出生時刻を知りません。仮に正午を入れて通常どおりチャートを計算すると、レスポンスにはもっともらしく見えるアセンダントとハウスのカスプが含まれますが、時刻の誤差 2 時間ごとにおよそ 1 サイン分ずれます。

そのため、time の代わりに timeUnknown: true を渡すことができます。

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

このモードで API が返す内容:

フィールド	値
`planets`	現地時間の正午で計算
`aspects`	計算されますが、月とのアスペクトは信頼できません (下記参照)
`houses`	`null`
`houseAspects`	`null`
`chartSect`	`null`
`siderealTime`	`null`
`timeUnknown`	説明のブロック: 何が省かれたか、月がどこにあり得るか

timeUnknown.moon ブロックには、その日の始まりと終わりの月の黄経、1 日で進んだ弧 (11.8-15.4°)、月が滞在したサインの一覧、changesSign フラグが含まれます。月は 1 日のうちにサインを変えることがあるため、1 つの数値の裏に隠さず、この範囲をユーザーに見せることをおすすめします。

このフラグを受け付けるのは /v1/chart と /v1/synastry です (シナストリーではパートナーごとに個別に設定できます)。その他のエンドポイントはハウスやアングルに依存するため、400 TIME_UNKNOWN_UNSUPPORTED を返します。フラグを黙って無視し、でっち上げたアセンダントを返すより、明示的なエラーのほうが望ましいからです。

API のバージョニング

メジャーバージョンは URL に含まれます (/v1/)。破壊的変更は /v2/ でのみ行い、既存バージョン内では行いません。詳しくはバージョニングをご覧ください。

GET /v1/version は現在のデプロイを返します。

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 は起動時にこれを呼び出して、「なぜ急に挙動が変わったのか」をデバッグできます。build_commit フィールドがデプロイを正確に特定します。

よく見かける誤った呼び出し

90 日分の本番ログの分析から、インテグレーターによくある 5 つの誤り:

/v1/<endpoint> ではなく /api/<endpoint>: WordPress の wp-json の習慣です。現在はヒント付きの JSON 404 を返します。
/v1/v1/<endpoint>: SDK が baseUrl = .../v1 で設定され、その上に /v1/X を付け足しています。現在は 308 リダイレクトです。
/v1/openapi.json ではなく /swagger.json: Postman/Insomnia の自動探索です。現在は 301 リダイレクトです。
Authorization: Bearer <jwt> なしの /v1/me, /v1/auth/keys/me → 401。トークンがヘッダーで渡されているか確認してください。
embed トークンではなく API キーを使った /v1/embed/natal → 401。embed エンドポイントが受け付けるのは、API キーではなく dashboard の 公開 embed トークン です。