TimeQL Documentation

Resolve profiles, moments, relations, and ranked candidates from datetime + location. TimeQL returns structured signals with symbolic semantics. Your AI interprets above the line.

Get started →

import requests

resp = requests.post(
    "https://api.timeql.com/api/v1/horoscope/natal",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "test",
        "datetime": "2000-01-01T12:00:00",
        "location": "Tokyo",
    },
)
print(resp.json())

Quickstart

Three steps to your first API call.

Create an account

Get an API key

Create an API key from the Dashboard. The key is shown only once — store it securely.

Make your first request

Use the code below to resolve a natal chart.

Some endpoints do not require full birth coordinates. mayan works with a date only, numerology works with birth_date only or becomes richer when you add full_name, body v2 returns compiled scores from body systems, dream works with dream_text first, and sukuyo accepts datetime but computes on the calendar date without using location.

Successful compute responses now include query_id, query_family, and a compact symbol_summary. You can use the returned query_id to attach optional context, inner signals, and later outcome feedback without changing the original compute request.

import requests

resp = requests.post(
    "https://api.timeql.com/api/v1/horoscope/natal",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "test",
        "datetime": "2000-01-01T12:00:00",
        "location": "Tokyo",
    },
)
print(resp.json())

curl -X POST https://api.timeql.com/api/v1/horoscope/natal \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "name": "test",
    "datetime": "2000-01-01T12:00:00",
    "location": "Tokyo"
  }'

Authentication

All API requests require an X-API-Key header. This includes both compute endpoints and optional observation endpoints. Create and manage keys from the Dashboard.

POST /api/v1/horoscope/natal HTTP/1.1
Host: api.timeql.com
Content-Type: application/json
X-API-Key: yao_sk_xxxxxxxxxxxxxxxxxxxxxxxx

Key management

Action	Description
Create	Issue a new key from the Dashboard. The key is shown only once.
Rotate	Revoke the old key and issue a new one. Both keys are valid during the transition period.
Revoke	Invalidate a key immediately. This action cannot be undone.

System Endpoints

These endpoints help clients discover the surface area, detect changes, inspect grouping metadata, and generate reduced schemas for agents. They are meta/discovery routes rather than compute routes.

No API key is required for these endpoints, and they do not consume credits.

GET /health Service health, deployed version, and runtime settings snapshot

GET /api/v1/updates Low-payload update check with latest_update and capabilities_digest

GET /api/v1/capabilities Machine-readable catalog of endpoints, required fields, purposes, and notes

GET /api/v1/endpoints Grouped endpoint inventory plus companion tool links

GET /api/v1/taxonomy Canonical TimeQL endpoint taxonomy with public grouping, engine identity, and artifact modes; use /api/v1/taxonomy/legacy or ?legacy=true for the older learning view

GET /api/v1/openapi-custom Filtered OpenAPI schema builder for GPTs and clients with endpoint-count limits

Western Astrology Canonical Paths

西洋占星術系の正規 path は /api/v1/horoscope/* です。AI エージェント、新規 SDK、GPT Actions schema ではこの namespace を使ってください。

旧 top-level path（例: /api/v1/natal_chart, /api/v1/transits）は v1 互換 alias として引き続き動作しますが、新規実装では使わないでください。/api/v1/horoscope/natal_chart も /api/v1/horoscope/natal の deprecated alias です。OpenAPI では旧 path を deprecated として表示し、catalog / capabilities / docs は /api/v1/horoscope/* の短い正規 path を扱います。

Current runtime surface:

/api/v1/horoscope/natal
/api/v1/horoscope/natal_chart (deprecated alias)
/api/v1/horoscope/event_chart
/api/v1/horoscope/return_chart
/api/v1/horoscope/transits
/api/v1/horoscope/transit_events
/api/v1/horoscope/progressions
/api/v1/horoscope/synastry
/api/v1/horoscope/triple_synastry
/api/v1/horoscope/composite
/api/v1/horoscope/election

Removed routes:

/api/v1/horoscope/daily
/api/v1/horoscope

Observation Endpoints (Optional Sidecar Loop)

TimeQL compute endpoints remain request-compatible. You do not need to send context or inner_signal to calculate a chart. Instead, every successful compute response returns a server-side query_id that can be used to attach sidecar events later.

Response metadata

{
  "query_id": "018f6f0b-8d86-7c36-b0da-2d3bfc8f1f7a",
  "query_family": "natal_chart",
  "symbol_summary": {
    "primary_symbols": ["sun:Gemini", "moon:Scorpio"],
    "house_system": "placidus"
  }
}

Observation endpoints

Endpoint	Use	Notes
`/api/v1/feedback/context`	顕在意識の文脈	何を知りたかったか、domain / intent、緊急度など
`/api/v1/signals/inner`	内なるシグナル	夢、直感、シンクロニシティ、身体感覚、反復イメージなど
`/api/v1/feedback/outcome`	縦追跡の結果	24時間後・7日後・30日後のしっくり度、行動、結果

These endpoints are meta/observation routes and currently cost 0 credits. Raw text can be handled as short-lived observation data, while derived features can be retained for longer analytics and routing.

Minimal flow

// 1. Call a compute endpoint as usual.
POST /api/v1/horoscope/natal

// 2. Read query_id from the response.
{
  "query_id": "018f6f0b-8d86-7c36-b0da-2d3bfc8f1f7a",
  "query_family": "natal_chart"
}

// 3. Optionally attach conscious context.
POST /api/v1/feedback/context
{
  "query_id": "018f6f0b-8d86-7c36-b0da-2d3bfc8f1f7a",
  "context": {
    "domain": "relationship",
    "intent": "clarity",
    "content": "相手との距離感をどう見ればいいか知りたい"
  }
}

// 4. Optionally attach latent / inner signals.
POST /api/v1/signals/inner
{
  "query_id": "018f6f0b-8d86-7c36-b0da-2d3bfc8f1f7a",
  "inner_signal": {
    "signal_kind": "dream",
    "content": "歯が抜ける夢を見た",
    "time_precision": "day"
  }
}

// 5. Later, close the loop with outcome feedback.
POST /api/v1/feedback/outcome
{
  "query_id": "018f6f0b-8d86-7c36-b0da-2d3bfc8f1f7a",
  "outcome": {
    "phase": "day_7",
    "resonance_score": 4,
    "action_taken": true,
    "outcome_score": 3
  }
}

Use context for explicit conscious framing, inner_signal for dreamlike or pre-verbal cues, and outcome for longitudinal truth. Do not make these fields mandatory before the initial compute call.

Credits

API requests are billed in credits. Endpoints are classified into 6 tiers by computational complexity.

Class	Credits	Example endpoints
Zero-cost	0	`health`, `capabilities`, `updates`, `taxonomy`, `endpoints`, `openapi-custom`, `feedback/context`, `signals/inner`, `feedback/outcome`
Light	1	`sukuyo`, `sukuyo/compatibility`, `sukuyo/fortune`
Core	5	`dream`, `kanshi`, `kyusei`, `ziweidoushu`, `liuren`, `sanmeigaku`, `horoscope/return_chart`, `sukuyo/compatibility/search`, `mayan`, `mayan/compatibility`, `numerology`, `numerology/compatibility`
Standard	10	`bazi`, `horoscope/natal`, `horoscope/transits`, `horoscope/synastry`, `horoscope/composite`, `seimei`, `horoscope/progressions`, `horoscope/election`
Intensive	25	`bazi/compatibility`, `bazi/fortune`, `qimen`, `qimen/matrix`, `kyusei/guidance`
Deep	100	`tekitenzui`, `jyotish`, `body v2`, `time v2`, `relation v2`
Simulation preview	250-500	`state_compiler` is internal in preview. If exposed later, recommended pricing is 250 credits for state-only compilation and 500 credits for an orchestrated agent-state tick before relation fan-out.

Billing

Paid plans use PAY.JP v1 recurring card billing. The server stores PAY.JP customer and subscription ids, billing status, the current period, and safe plan metadata; raw card numbers are never sent to TimeQL.

Plan	Monthly price	Included credits	Renewal behavior
Builder	JPY 7,980	15,000 / mo	Credits are added on paid renewal
Growth	JPY 24,800	90,000 / mo	Credits are added on paid renewal
Scale	JPY 79,800	300,000 / mo	Credits are added on paid renewal

The dashboard reads GET /auth/billing/config for the public PAY.JP key, configured self-serve plans, and current billing state. The dedicated checkout screen creates a payjp.js token with 3D Secure iframe authentication, then calls POST /auth/billing/payjp/checkout with a card_token and plan; the server verifies the token's three_d_secure_status before creating the subscription and never receives raw card fields. Existing subscriptions can use POST /auth/billing/payjp/change-plan, POST /auth/billing/payjp/resume, or POST /auth/billing/payjp/cancel.

The current billing state is also exposed on /auth/me as billing_status, billing_plan, and current_period_end. API credit consumption still uses token_balance; paid-plan checkout, plan changes, and renewals add the plan's included credits while existing credits carry forward.

Billing webhooks at POST /auth/billing/payjp/webhook are treated as the source of truth for paid renewals. Manual admin credit refill skips PAY.JP-managed users so a monthly paid renewal cannot be granted twice.

Symbolic Semantics

TimeQL returns not only numeric outputs, but also structured symbolic semantics: elements, polarity, archetypes, relation categories, activation states, and ranked signals.

L0–L5: Computed by TimeQL

Layer	What it does	Example fields
L0 Input	Accept datetime + location	`datetime`, `timezone`, `location`
L1 Conversion	Calendar, stems, branches, positions	`pillars`, `rashi`, `house_cusps`
L2 Cycles	Time progression systems	`daiun`, `dasha`, `transits`
L3 Symbols	Attach meaning to computed values	`element`, `keywords`, `reading_note`
L4 Relations	Cross-entity relationships	`aspects`, `compatibility_score`, `convergence`
L5 Progression	Timeline, ranking, scoring	`timeline`, `best_slots[]`, `direction_rank[]`

L6: Interpretation — above the line

TimeQL does not generate final narrative. L6 interpretation is handled by your application, your AI, or by UN as the downstream orchestration layer.

The notes and reading_note fields in responses are structured symbolic descriptions (L3), not L6 narrative. They provide element associations, archetype keywords, and positional meanings that your interpretation layer can use as input.

Response Profiles

All public non-dream divination endpoints accept an optional response_profile. Use full for the source-of-truth payload, facts to drop verbose narrative branches where present, and agent for a compact machine-oriented payload. query_id, query_family, and symbol_summary stay attached in every profile.

Astronomical positional endpoints expose family-specific compact schemas. The other non-dream systems expose summary plus packed data so agents can inspect the same calculation result with lower token cost.

Datetime / Timezone Contract

人間のユーザーと AI エージェントの解釈がずれないように、TimeQL は全エンドポイントで同じ日時ルールを使います。占星術系の ASC / MC / ハウスは時刻に敏感なので、datetime や transit_date は次のルールで渡してください。

Input pattern	How TimeQL interprets it
`2026-04-08T18:32:00-04:00`	オフセット付きISO。絶対時刻として扱います。この例は New York の 18:32 EDT で、UTC では `2026-04-08T22:32:00Z` です。
`2026-04-08T22:32:00Z` または `2026-04-08T22:32:00+00:00`	UTC の絶対時刻として扱います。上の `18:32:00-04:00` と同一瞬間なので、同一の計算結果になります。
`2026-04-08T18:32:00` (naive)	オフセットがないため、request の `timezone` におけるローカル時刻として解釈します。例: `timezone="America/New_York"` なら 18:32 EDT です。
`timezone` omitted	location から推定できる場合は推定し、推定できない場合は UTC として扱います。曖昧さを避けるため、AI エージェントには明示的な `timezone` またはオフセット付きISOを渡させてください。

内部計算では、入力日時を UTC の計算時刻に正規化してからチャートエンジンに渡します。timezone は naive datetime の解釈とローカル出力のために使われ、UTC 正規化後に二重適用されることはありません。

Equivalent instants must produce equivalent results. Example: 2026-04-08T18:32:00-04:00 and 2026-04-08T22:32:00Z are the same moment, so identical outputs are expected. 逆に 2026-04-08T18:32:00+00:00 は別の瞬間なので、ASC / MC / houses は変わります。

/api/v1/horoscope/transits では、natal_angles は出生図の固定アングルで transit_date では変わりません。時点依存の ASC / MC / DSC / IC を見る場合は transit_angles を使ってください。

/api/v1/horoscope/event_chart は natal data を使わない moment chart です。出生データの代わりに、日時と場所の組み合わせで天空図を返します。AI エージェントには、natal-relative の transits と混同させず、moment-only chart が必要なときは event_chart を選ばせてください。

Full endpoint-by-endpoint matrix: DATETIME_TIMEZONE_CONTRACT.md

出生図

POST /api/v1/horoscope/natal 10 credits

出生日時と場所から、惑星位置・ハウスカスプ・アスペクト・3区分4区分を含む完全な出生図を計算します。ASC / DSC / MC / IC、月のノード（北ノード・南ノード）、Chiron、lilith_mean、Part of Fortune、Vertex、Anti-Vertex を返し、include_lilith_true 指定時のみ lilith_true も追加します。後方互換のため旧入力 include_true_lilith と旧出力 lilith / true_lilith も当面併記します。

パラメータ

フィールド	型		説明
`name`	string	必須	対象者の名前
`datetime`	string	必須	出生日時（ISO 8601形式）
`location`	string	必須	出生地（都市名または緯度経度）
`house_system`	string	任意	ハウスシステム。デフォルト: `placidus`
`include_lilith_true`	boolean	任意	`true` のとき `lilith_true` を追加。デフォルトは `false`。旧 `include_true_lilith` も利用可
`response_profile`	string	任意	`full` / `facts` / `agent`。デフォルト: `full`

facts は interpretations を除いた計算結果、agent は compact な機械読取プロファイルです。完全な source of truth が必要な場合は full を使ってください。

リクエスト例

{
  "name": "田中太郎",
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo"
}

レスポンス例（抜粋）

{
  "name": "田中太郎",
  "planets": {
    "sun": {"longitude": 84.12, "sign": "Gemini", "degree": 24.12, "house": 10},
    "moon": {"longitude": 218.45, "sign": "Scorpio", "degree": 8.45, "house": 3},
    // ... 10天体 + North/South Node
  },
  "houses": [243.5, 271.2, /* ... 12カスプ */],
  "aspects": [...],
  "modalities": {"cardinal": 4, "fixed": 3, "mutable": 5},
  "elements": {"fire": 3, "earth": 2, "air": 4, "water": 3}
}

四柱推命

POST /api/v1/bazi 25 credits

四柱推命による命式を作成します。蔵干分野・通変星・十二運・神殺・大運を含む本格的な命式分析。用神情報は /api/v1/bazi のレスポンス本体に含まれ、別エンドポイントとして公開されているのは相性診断と運勢分析です。

サブエンドポイント

/api/v1/bazi/compatibility 相性診断

/api/v1/bazi/fortune 運勢分析

パラメータ

フィールド	型		説明
`datetime`	string	必須	出生日時
`location`	string	任意	出生地
`gender`	string	必須	`male` / `female`
`use_solar_time`	boolean	任意	真太陽時補正。デフォルト: `true`

リクエスト例

{
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo",
  "gender": "male"
}

レスポンス例（抜粋）

{
  "pillars": {
    "year":  {"stem": "庚", "branch": "午"},
    "month": {"stem": "壬", "branch": "午"},
    "day":   {"stem": "丙", "branch": "辰"},
    "hour":  {"stem": "乙", "branch": "未"}
  },
  "zoukan": [...],
  "tsuhensei": [...],
  "daiun": [...],
  "kuubou": ["寅", "卯"]
}

滴天髄

POST /api/v1/tekitenzui 100 credits

滴天髄理論に基づく高度な命理分析を実行します。旺相休囚死・仮数測定・五行バランス補正・格局判定・用神判定・大運分析を含む包括的な分析。

パラメータ

フィールド	型		説明
`datetime`	string	必須	出生日時
`location`	string	任意	出生地
`gender`	string	必須	`male` / `female`

リクエスト例

{
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo",
  "gender": "male"
}

算命学

POST /api/v1/sanmeigaku 25 credits

算命学に基づく陰占・陽占を計算します。二十八元蔵干・天冲殺・十大主星・十二大従星・大運を含む本格的な命式。

パラメータ

フィールド	型		説明
`datetime`	string	必須	出生日時
`location`	string	任意	出生地
`gender`	string	必須	`male` / `female`

リクエスト例

{
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo",
  "gender": "male"
}

インド占星術

POST /api/v1/jyotish 25 credits

インド占星術のチャートを計算します。ラグナ・9グラハ・27ナクシャトラ・ヴァルガ・シャドバラ・アシュタカヴァルガ・ヨーガ・ヴィムショッタリーダシャーに対応。Lahiriアヤナムシャ使用。

サブエンドポイント

/api/v1/jyotish/gochara ゴーチャラ（トランジット）分析

パラメータ

フィールド	型		説明
`datetime`	string	必須	出生日時
`location`	string	必須	出生地
`gender`	string	任意	`male` / `female`

リクエスト例

{
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo"
}

レスポンス例（抜粋）

{
  "lagna": {"rashi": "Tula", "degree": 15.42, "nakshatra": "Swati"},
  "grahas": {
    "surya": {"rashi": "Vrishabha", "degree": 0.68, "nakshatra": "Krittika"},
    "chandra": {"rashi": "Tula", "degree": 14.92, "nakshatra": "Swati"},
    // ... 9 Grahas
  },
  "vimshottari_dasha": {...},
  "shadbala": {...},
  "yogas": [...]
}

紫微斗数

POST /api/v1/ziweidoushu 25 credits

紫微斗数の命盤を作成します。十四主星・六吉星・六煞星・化曜の配置と十二宮の分析を返します。

パラメータ

フィールド	型		説明
`datetime`	string	必須	出生日時（旧暦自動変換）
`gender`	string	必須	`male` / `female`
`location`	string	任意	出生地

リクエスト例

{
  "datetime": "1990-06-15T14:30:00",
  "gender": "male"
}

マヤ暦

POST /api/v1/mayan 5 credits

ドリームスペル（またはGMT古典相関）によるマヤ暦KINプロファイルを計算します。銀河の音・太陽の紋章・ウェイブスペル・城・5ポジションオラクルを返します。

サブエンドポイント

/api/v1/mayan/compatibility 2人のKIN相性分析

パラメータ

フィールド	型		説明
`date`	string	必須	日付 (YYYY-MM-DD)
`correlation`	string	任意	`dreamspell`（デフォルト, Argüelles式）/ `gmt`（古典GMT相関）

correlationパラメータについて

dreamspellはJosé Argüellesが普及させた現代的なシステムで、西洋で広く使われています。gmt（グッドマン・マルティネス・トンプソン相関）は考古学的・古典的なマヤ暦の計算方式です。

リクエスト例

{
  "date": "1990-06-15",
  "correlation": "dreamspell"
}

レスポンス例（抜粋）

{
  "date": "1990-06-15",
  "correlation": "dreamspell",
  "kin": 68,
  "tone": {
    "number": 3,
    "name_ja": "電気",
    "name_en": "Electric",
    "action": "活性化する",
    "power": "奉仕",
    "essence": "絆"
  },
  "seal": {
    "number": 8,
    "name_ja": "星",
    "name_en": "Star",
    "color_ja": "黄",
    "power": "優雅",
    "action": "美化する",
    "essence": "美"
  },
  "wavespell_number": 6,
  "wavespell_position": 3,
  "wavespell_seal": {"name_ja": "世界の橋渡し", "color_ja": "白", /* ... */},
  "castle_number": 2,
  "castle_color_ja": "白",
  "castle_direction": "北",
  "castle_name_ja": "横断の白い城",
  "oracle": {
    "core":     {"kin": 68, "tone": {/* ... */}, "seal": {/* ... */}},
    "analog":   {"kin": 108, /* ... */},
    "antipode": {"kin": 198, /* ... */},
    "occult":   {"kin": 193, /* ... */},
    "guide":    {"kin": 8,   /* ... */}
  },
  "is_gap": false,
  "tone_reading": {/* キーワード辞書 */},
  "seal_reading": {/* キーワード辞書 */},
  "wavespell_reading": {/* キーワード辞書 */},
  "castle_reading": {/* キーワード辞書 */},
  "calculation_time_ms": 0.4
}

数秘術（ピタゴリアン + カバラ）

POST /api/v1/numerology 5 credits

生年月日だけ、または生年月日 + フルネームから数秘術チャートを計算します。Life Path / Destiny / Soul / Personality / Birthday / Maturity / Habit、4期のPinnacles & Challenges、パーソナルイヤー、欠落数、気質バランス、レーダーチャート、カバラ生命の木を返します。full response では shared compiler / observation sidecar も付与されます。

サブエンドポイント

/api/v1/numerology/compatibility 二人の数秘術相性分析

パラメータ

フィールド	型		説明
`birth_date`	string	必須	生年月日 (YYYY-MM-DD)
`full_name`	string	任意	フルネーム。ひらがな/カタカナ/ローマ字に対応。漢字は非対応。省略時は date-only モード
`target_date`	string	任意	パーソナルサイクル算出対象日 (YYYY-MM-DD)
`include_kabbalah`	boolean	任意	カバラ生命の木レイヤーを含める。デフォルト: `true`

入力モード

date-only モードでは life_path / birthday / habit / pinnacles / challenges / personal_cycle / radar_chart / kabbalah を返します。
full chart モードでは full_name を追加し、destiny / soul / personality / maturity / missing_numbers / temperament が増えます。名前はひらがな/カタカナ/ローマ字に対応し、内部でローマ字へ正規化されます。漢字は非対応です。

リクエスト例

{
  "birth_date": "1990-05-15",
  "full_name": "たなか はなこ",
  "target_date": "2026-03-28",
  "include_kabbalah": true
}

レスポンス例（抜粋）

{
  "name_romanized": "TANAKA HANAKO",
  "birth_date": "1990-05-15",
  "core": {
    "life_path": 3,
    "destiny": 11,
    "soul": 6,
    "personality": 5,
    "birthday": 15,
    "maturity": 5,
    "habit": 1,
    "master_numbers_found": [11],
    "karmic_numbers_found": []
  },
  "pinnacles": [{"period": 1, "number": 8, "age_start": 0, "age_end": 33, "meaning": "実務力と成果"}],
  "personal_cycle": {"personal_year": 1, "personal_month": 3, "personal_day": 8},
  "missing_numbers": {"missing": [4, 7], "present_counts": {"1": 2}},
  "temperament": {"physical": 5, "mental": 7, "emotional": 4, "intuitive": 6},
  "radar_chart": {"execution": 6, "expression": 8, "vision": 7},
  "kabbalah": {
    "life_path_sephirah": {"name_en": "Binah", "meaning_ja": "理解・構造"},
    "tree_path": [{/* ... */}]
  },
  "interpretations": {
    "life_path": {"title": "創造者", "career": "表現・企画・教育..."},
    "personal_year": {"theme": "新しい始まり"}
  },
  "calculation_time_ms": 0.7
}

夢分析

POST /api/v1/dream 5 credits

自由記述の夢を TimeQL の dream_vector に変換します。シンボル、行動、場所、身体印象、モチーフ、ドメイン仮説、時間スケール仮説を deterministic に返します。

パラメータ

フィールド	型		説明
`dream_text`	string	必須	夢の自由記述
`dream_at`	string	任意	夢を見た時刻（ISO形式）
`time_precision`	string	任意	`exact` / `day` / `unknown`
`recurring`	boolean	任意	繰り返し見る夢か
`lucidity`	string	任意	`low` / `medium` / `high` / `unknown`
`wake_affect`	object	任意	起床時の感情価と覚醒度
`user_hints.recent_stress_domain`	string	任意	直近で意識しているストレス領域（tie-break のみ）

重い入力では /api/v1/dream がタイムアウト（504）する場合があります。長文は分割し、429/接続断時は指数バックオフ（1s, 2s, 4s）で再試行してください。

リクエスト例

{
  "dream_text": "歯が抜けて、誰かに追われながら暗い道を逃げていた",
  "dream_at": "2026-03-30T05:10:00+09:00",
  "time_precision": "exact",
  "recurring": false,
  "lucidity": "low"
}

レスポンス例（抜粋）

{
  "query_family": "dream",
  "symbol_summary": {
    "primary_symbols": ["teeth_loss", "being_chased", "dark_road"],
    "primary_domains": ["family", "anxiety", "transition"],
    "time_horizon": "near_term"
  },
  "dream_vector": {
    "symbols": [
      {"key": "teeth_loss", "taxonomy": "body", "salience": 0.9},
      {"key": "being_chased", "taxonomy": "action", "salience": 0.88}
    ],
    "motifs": ["collapse", "transition", "pursuit"],
    "risk_signals": ["family_strain", "acute_pressure"]
  },
  "domain_hypotheses": [
    {"domain": "anxiety", "weight": 0.4, "supporting_symbols": ["teeth_loss", "being_chased"]}
  ],
  "time_horizon": {"bucket": "near_term", "confidence": 0.7},
  "action_signals": ["slow_down", "protect_boundary", "prepare_for_change"],
  "source_variants": [{"label": "warning_weighted", /* ... */}],
  "calculation_time_ms": 0.5
}

Body v2

POST /api/v2/body 100 credits

出生日時・場所・名前から natal / Tekitenzui / Jyotish / numerology / Sanmeigaku / Ziwei Doushu / Sukuyo を内部計算し、TimeQL 独自の body_scores にコンパイルします。v2 artifact は body / time / relation の3本に限定し、decision は人間または client が行います。デフォルトの response_profile=scores は最終スコアに加えて score_basis / confidence_summary / available_layers / missing_or_degraded を返します。full / debug は structured P3 prior contract の body_priors を追加します。/api/v2/persona は互換 alias です。

パラメータ

フィールド	型		説明
`name`	string	必須	表示名または安定した body label
`gender`	string	必須	`male` / `female`。`unknown` は Body v2 では無効。gendered cycle systems に使います
`datetime`	string	必須	出生日時。日付のみの場合は正午として扱います
`latitude` / `longitude`	number	任意	出生地の座標。`address` または `location` でも指定できます
`address` / `location`	string	任意	出生地。座標未指定時に解決します
`timezone`	string	任意	naive datetime の解釈に使う timezone
`full_name`	string	任意	数秘術の名前要素を含める場合に指定
`include_time`	boolean	任意	false の場合は時刻依存 source の重みを下げます
`response_profile`	string	任意	`scores`（デフォルト）/ `full` / `debug`。full/debug は `body_priors` と `compiler_diagnostics` を含みます

リクエスト例

{
  "name": "test",
  "gender": "male",
  "datetime": "2000-01-01T12:00:00",
  "location": "Tokyo",
  "full_name": "Taro Yamada",
  "response_profile": "scores"
}

レスポンス例（抜粋）

{
  "schema_version": "timeql-body-v2",
  "response_profile": "scores",
  "query_family": "body",
  "score_basis": "symbolic_body_prior",
  "identity_seed": {
    "name": "test",
    "datetime": "2000-01-01T12:00:00",
    "timezone": "Asia/Tokyo",
    "full_name": "Taro Yamada",
    "gender": "male"
  },
  "body_scores": {
    "risk_salience": 0.67,
    "trust_openness": 0.49,
    "verification_need": 0.74,
    "response_latency_tendency": 5
  },
  "timeql_traits": {
    "stability": 0.66,
    "role_adaptation": 0.62,
    "agency_drive": 0.66,
    "social_distance_sensitivity": 0.61
  },
  "confidence_summary": {
    "overall": 0.78,
    "input_completeness": 1.0,
    "source_agreement": 0.78,
    "fidelity_tier": "symbolic_prior"
  },
  "available_layers": ["symbolic_prior.western", "symbolic_prior.tekitenzui"],
  "missing_or_degraded": []
}

Legacy humanlm_priors remains available in full / debug for early v2 clients. New clients that need structured priors should request response_profile=full or debug and read body_priors.

{
  "response_profile": "full",
  "body_priors": {
    "metadata": {
      "schema_version": "timeql-body-priors-v1",
      "humanlm_alignment": "prior_only",
      "contextual_state_available": false
    },
    "belief_prior": {
      "summary": "Uncertainty should be reduced before committing to strong claims.",
      "source_contribution": {"tekitenzui": 0.3, "ziwei": 0.2},
      "confidence": {"input_completeness": 0.97, "source_agreement": 0.72, "final": 0.88}
    },
    "goal_tendencies": {
      "items": [
        {"goal_id": "verify_before_action", "goal": "verify claims before pushing others into action", "strength": 0.74}
      ]
    },
    "stance_tendencies_by_target_type": {
      "targets": {
        "authority_claims": {
          "target_type": "authority claims",
          "default_position": "autonomy-preserving and evidence-seeking",
          "strength": 0.64
        }
      }
    }
  }
}

Time v2

POST /api/v2/time 100 credits

対象時点・期間を TimeQL の time_scores artifact にコンパイルします。body_reference なしでは対象時点の /api/v1/horoscope/event_chart から月相・アングル・逆行・主要アスペクト密度を抽出し、provenance.compiler_status=event_chart_preview を返します。body_reference がある場合は body_reference.gender に応じて body_relative.long_cycle.tekitenzui_daiun / body_relative.annual_cycle.tekitenzui_ryuunen を fuse し、さらに body_relative.short_transit.jyotish_gochara を可能な範囲で fuse して time_scope=body_relative を返します。体側の timing_sensitivity は /api/v2/body に残し、decision は人間または client が行います。

パラメータ

フィールド	型		説明
`target_datetime`	string	必須	対象日時。日付のみの場合は正午として扱います
`latitude` / `longitude`	number	任意	対象地点の座標。`address` または `location` でも指定できます
`address` / `location`	string	任意	対象地点。座標未指定時に解決します
`timezone`	string	任意	naive datetime の解釈に使う timezone
`window`	object	任意	`unit`: hour/day/week/month、`size`: 1-120
`body_reference`	object	任意	body-relative time scoring のための出生参照。`gender` は body artifact から引き継ぎ、long/annual cycle と Jyotish gochara short-transit fusion に使います
`response_profile`	string	任意	`scores`（デフォルト）/ `full` / `debug`。full/debug は `time_priors` と `compiler_diagnostics` を含みます

リクエスト例

{
  "target_datetime": "2026-04-27T09:00:00+09:00",
  "location": "Tokyo",
  "timezone": "Asia/Tokyo",
  "window": {"unit": "day", "size": 7},
  "response_profile": "scores"
}

レスポンス例（抜粋）

{
  "schema_version": "timeql-time-v2",
  "artifact_kind": "time",
  "query_family": "time",
  "score_basis": "local_moment_event_chart",
  "time_scope": "local_moment",
  "time_scores": {
    "temporal_pressure": 0.62,
    "temporal_support": 0.54,
    "temporal_volatility": 0.48,
    "initiative_window_strength": 0.57,
    "delay_friction": 0.36,
    "verification_window_strength": 0.71,
    "recovery_window_support": 0.59
  },
  "confidence_summary": {
    "overall": 0.49,
    "input_completeness": 0.62,
    "source_agreement": 0.5,
    "fidelity_tier": "local_moment_baseline"
  },
  "available_layers": ["local_moment.western_event_chart"],
  "missing_or_degraded": ["body_reference_absent", "body_relative_layers_unavailable"],
  "provenance": {
    "source_systems": ["western_event_chart"],
    "compiler_status": "event_chart_preview",
    "source_fusion_stage": "event_chart_only",
    "time_scope": "local_moment"
  }
}

宿曜

POST /api/v1/sukuyo 1 credit

本命宿を返します。入力は datetime ですが、計算は月宿傍通暦ベースで日付単位です。出生時刻や location は使いません。

サブエンドポイント

/api/v1/sukuyo/compatibility 二人の宿曜相性（三九法）

/api/v1/sukuyo/fortune 本命宿基準の日運・凌犯・六害

/api/v1/sukuyo/compatibility/search 基準宿からの相性検索

パラメータ

フィールド	型		説明
`name`	string	必須	名前
`datetime`	string	必須	生年月日時（ISO形式）。時刻は受け取るが計算自体は日付単位
`include_details`	boolean	任意	宿の詳細情報（恋愛・適職・接し方）を含める。デフォルト: `true`

リクエスト例

{
  "name": "太郎",
  "datetime": "1990-06-15T14:30:00",
  "include_details": true
}

レスポンス例（抜粋）

{
  "name": "太郎",
  "birth_datetime": "1990-06-15T14:30:00",
  "honmei_shuku": {
    "number": 11,
    "name_japanese": "軫宿",
    "reading": "しんしゅく",
    "group": "南方朱雀",
    "element": "水",
    "love": "社交的だが慎重に距離を測る..."
  },
  "lunar_calendar": {"year": 1990, "month": 5, "day": 23, "is_leap": false},
  "calculation_method": "月宿傍通暦",
  "calculation_time_ms": 0.4
}

Relation v2

POST /api/v2/relation 100 credits

subject / target の interaction を TimeQL の relation_scores artifact にコンパイルする source-preview endpoint です。双方の datetime と birth location がある person_to_person request では source_systems=["sukuyo_compatibility","western_synastry"]、provenance.compiler_status=relation_source_fusion_preview を返します。任意の relation_history.events は interaction_event_v1 の observed evidence として accumulated_relation_field に積み、任意の target_time がある場合は Time v2 local moment と subject / target body-relative time を relation_time_modulation に変換して current_relation に fusion します。datetime-only では sukuyo_relation_preview、入力不足時は relation_stub_preview に fallback します。v2 artifact は body / time / relation の3本に限定し、decision endpoint は提供しません。

パラメータ

フィールド	型		説明
`subject`	object	必須	関係を見る主体。通常は `name`, `datetime`, `location` など body seed と同等の入力
`target`	object	必須	相手側の入力。shape は `subject` と同じ
`relation_type`	string	任意	`person_to_person`（デフォルト）/ `person_to_group` / `person_to_place` / `person_to_event`
`relation_history`	object	任意	`events` 配列で観測済み interaction を渡す。`event_type`, `intensity`, `recency_days` / `timestamp`, `actor_role`, `target_role`, `direction`, `source_kind`, `source_confidence` を `interaction_event_v1` evidence として扱う
`target_time`	object	任意	その時点の relation overlay。`datetime` と location を渡すと Time v2 local moment から `relation_time_modulation` を作る
`response_profile`	string	任意	`scores`（デフォルト）/ `full` / `debug`。`full` / `debug` は source contribution と confidence を含む

リクエスト例

{
  "subject": {
    "name": "A",
    "datetime": "1990-06-15T14:30:00",
    "location": "Tokyo"
  },
  "target": {
    "name": "B",
    "datetime": "1992-03-20T09:00:00",
    "location": "Osaka"
  },
  "relation_type": "person_to_person",
  "target_time": {
    "datetime": "2026-04-27T10:00:00+09:00",
    "location": "Tokyo, Japan",
    "timezone": "Asia/Tokyo"
  },
  "relation_history": {
    "events": [
      {"event_id": "evt_001", "event_type": "trust", "intensity": 0.8, "recency_days": 14, "actor_role": "target", "direction": "target_to_subject", "source_kind": "message_log", "source_confidence": 0.82},
      {"event_id": "evt_002", "event_type": "repair", "intensity": 0.6, "timestamp": "2026-04-24T18:30:00+09:00", "actor_role": "both", "direction": "bidirectional", "source_kind": "manual", "source_confidence": 0.76}
    ]
  },
  "response_profile": "scores"
}

レスポンス例（抜粋）

{
  "schema_version": "timeql-relation-v2",
  "artifact_kind": "relation",
  "query_family": "relation",
  "score_basis": "symbolic_relation_prior_fusion",
  "relation_type": "person_to_person",
  "relation_scores": {
    "baseline_resonance": 0.79,
    "friction_potential": 0.37,
    "complementarity": 0.66,
    "trust_distance": 0.38,
    "communication_compatibility": 0.72,
    "conflict_intensity_potential": 0.30,
    "boundary_pressure": 0.30,
    "role_balance": 0.84,
    "cooperation_potential": 0.73,
    "recovery_ease": 0.76
  },
  "confidence_summary": {
    "overall": 0.68,
    "input_completeness": 0.78,
    "source_agreement": 0.84,
    "fidelity_tier": "symbolic_prior_fusion"
  },
  "available_layers": ["base_relation.sukuyo_compatibility", "base_relation.western_synastry"],
  "missing_or_degraded": ["target_time_absent", "observed_history_absent", "accumulated_relation_field_absent"],
  "provenance": {
    "source_systems": ["sukuyo_compatibility", "western_synastry"],
    "compiler_status": "relation_source_fusion_preview",
    "source_fusion_available": true,
    "source_fusion_stage": "relation_source_fusion_v1",
    "artifact_triad": ["body", "time", "relation"],
    "decision_endpoint_available": false
  }
}

scores は flat な relation_scores を返します。relation_history を渡した場合は score_basis=symbolic_prior_observed_history_fusion、target_time を渡した場合は score_basis=symbolic_prior_time_modulation_fusion になり、full / debug で relation_layers.base_relation, relation_layers.accumulated_relation_field, relation_layers.accumulated_relation_field.event_summary, relation_layers.relation_time_modulation, relation_layers.relation_time_modulation.components.subject_body_relative, relation_layers.current_relation を確認できます。Current sources are sukuyo_compatibility and western_synastry for eligible person-to-person input. Future source candidates are western_composite, sanmeigaku_compatibility, bazi_compatibility, and numerology_compatibility.

Agent simulation runtime は /api/v2/body, /api/v2/time, /api/v2/relation を内部 state_compiler に渡して agent_state を作れます。preview では /api/v2/state は公開しません。運用手順は Agent simulation state を参照してください。

Agent Simulation State

v2 を使ってエージェントに TimeQL の luck input を与える場合、public API は /api/v2/body, /api/v2/time, /api/v2/relation の3つだけを呼びます。最終的な runtime state は client runtime または internal service が state_compiler で作ります。preview では /api/v2/state は public endpoint として提供しません。

Minimal usage

Step	Call	Persist / use
1	`POST /api/v2/body`	仮想 agent ごとに一度作成し、stable body substrate として保存します
2	`POST /api/v2/time`	simulation tick ごとに呼び、body-relative temporal modulation として現在 state に適用します
3	`POST /api/v2/relation`	agent 同士の interaction が発生したときに呼び、observed relation history と current relation を更新します
4	`state_compiler`	body / time / relation を合成し、`agent_state`, `state_scores`, `state_deltas` を作ります

Random agent seed

simulation client はランダム生成した個人 seed を送るだけで開始できます。gender は male / female のどちらかが必須で、unknown は無効です。full_name は名前ベース source の読みとして使うため、ひらがな・カタカナ・romaji・alphabetic text を推奨します。漢字だけの名前は name-number source には使いません。

{
  "agent_id": "agent_001",
  "name": "Agent A",
  "full_name": "TARO TANAKA",
  "gender": "male",
  "datetime": "1990-05-15T08:30:00",
  "location": "Tokyo, Japan",
  "timezone": "Asia/Tokyo",
  "include_time": true
}

Runtime flow

synthetic person seed
  -> POST /api/v2/body
  -> stable body substrate

simulation clock tick
  -> POST /api/v2/time
  -> temporal modulation

agent interaction log
  -> POST /api/v2/relation
  -> relation modulation

body + time + relation
  -> state_compiler
  -> agent_state

State shape

The compiled state exposes six runtime dimensions for agent behavior, dialogue policy, and simulation logging. These are state scores, not final decisions or moral labels.

{
  "artifact_kind": "agent_state",
  "state_scores": {
    "belief_state": 0.67,
    "value_state": 0.55,
    "goal_state": 0.46,
    "stance_state": 0.71,
    "emotion_state": 0.68,
    "communication_state": 0.59
  },
  "state_deltas": {
    "emotion_state": {
      "previous": 0.52,
      "current": 0.68,
      "delta": 0.16,
      "direction": "increased"
    }
  }
}

API pricing guidance

Current public API usage is billed by the underlying v2 artifact calls: /api/v2/body, /api/v2/time, and /api/v2/relation are each Deep class, 100 credits. Body should usually be cached per agent; time is paid per simulation tick; relation is paid only when a relation artifact is recalculated.

Mode	Recommended credits	When to use
Current public triad	100 per artifact	Call body/time/relation directly and compile state in your runtime
Future state-only compiler API	250	Client supplies existing body/time/relation artifacts and asks TimeQL to compile `agent_state`
Future orchestrated agent-state tick	500+	TimeQL orchestrates artifact refresh plus state compilation. Relation fan-out and large batches should be additive or custom-priced

The higher price is intentional: agent-state compilation composes multiple Deep artifacts and is usually called repeatedly in simulation loops. Do not expose it as a cheap convenience wrapper over the triad.

シナストリー

POST /api/v1/horoscope/synastry 10 credits

二人の出生図を比較し、相性分析を行います。ハウスオーバーレイ、ハーモニックアスペクト、デイビソン関係チャートを含みます。

パラメータ

フィールド	型		説明
`person1`	object	必須	1人目の出生データ（`name`, `datetime`, `location`）
`person2`	object	必須	2人目の出生データ
`include_auxiliary_points`	boolean	任意	補助感受点（Lilith/PoF/Vertex）を返すか。デフォルト: `false`
`include_lilith_true`	boolean	任意	`lilith_true` を返すか。旧 `include_true_lilith` 互換

リクエスト例

{
  "person1": {
    "name": "太郎",
    "datetime": "1990-06-15T14:30:00",
    "location": "Tokyo"
  },
  "person2": {
    "name": "花子",
    "datetime": "1992-03-20T09:00:00",
    "location": "Osaka"
  }
}

トリプルシナストリー

POST /api/v1/horoscope/triple_synastry 10 credits

三人の相性を同時に分析します。グループ内の調和度、各人の役割（リーダー・メディエーター・カタリスト）を判定します。

パラメータ

フィールド	型		説明
`person1`	object	必須	1人目の出生データ
`person2`	object	必須	2人目の出生データ
`person3`	object	必須	3人目の出生データ
`include_auxiliary_points`	boolean	任意	補助感受点（Lilith/PoF/Vertex）を返すか。デフォルト: `false`
`include_lilith_true`	boolean	任意	`lilith_true` を返すか。旧 `include_true_lilith` 互換

リクエスト例

{
  "person1": {"name": "A", "datetime": "1990-01-01T12:00:00", "location": "Tokyo"},
  "person2": {"name": "B", "datetime": "1991-06-15T08:00:00", "location": "Osaka"},
  "person3": {"name": "C", "datetime": "1992-12-25T20:00:00", "location": "Kyoto"}
}

コンポジット

POST /api/v1/horoscope/composite 10 credits

二人の中間点から関係性の本質を示すコンポジットチャートを作成します。ミッドポイント方式とデイビソン方式に対応。

パラメータ

フィールド	型		説明
`person1`	object	必須	1人目の出生データ
`person2`	object	必須	2人目の出生データ
`method`	string	任意	`midpoint`（デフォルト）/ `davison`
`include_auxiliary_points`	boolean	任意	補助感受点（Lilith/PoF/Vertex）を返すか。デフォルト: `false`
`include_lilith_true`	boolean	任意	`lilith_true` を返すか。旧 `include_true_lilith` 互換

リクエスト例

{
  "person1": {"name": "太郎", "datetime": "1990-06-15T14:30:00", "location": "Tokyo"},
  "person2": {"name": "花子", "datetime": "1992-03-20T09:00:00", "location": "Osaka"},
  "method": "midpoint"
}

四柱推命相性

POST /api/v1/bazi/compatibility 25 credits

2人の四柱推命チャートを比較し、五行の相性・日干の関係・地支の合冲を分析。恋愛・ビジネス・友人関係に対応。

パラメータ

名前	型	説明
`person1_datetime`	string	1人目の出生日時
`person2_datetime`	string	2人目の出生日時
`person1_gender`	string	1人目の性別（任意）
`person2_gender`	string	2人目の性別（任意）

算命学相性

POST /api/v1/sanmeigaku/compatibility 10 credits

2人の算命学チャートを比較。天中殺グループの組み合わせ・日干の五行相性・地支の位相法クロス分析による総合相性スコア。

パラメータ

名前	型	説明
`datetime_a`	string	1人目の生年月日
`datetime_b`	string	2人目の生年月日

九星気学相性

POST /api/v1/kyusei/compatibility 5 credits

2人の九星（本命星・月命星）の五行関係から相性を判定。相生・相剋・比和の関係性とアドバイス。

パラメータ

名前	型	説明
`person1_datetime`	string	1人目の生年月日
`person2_datetime`	string	2人目の生年月日

宿曜相性

POST /api/v1/sukuyo/compatibility 1 credit

二人の本命宿を比較し、三九法による双方向ラベルと総合解釈を返します。入力は datetime ですが、比較は日付単位で行い location は不要です。

パラメータ

フィールド	型		説明
`person1_name`	string	必須	1人目の名前
`person1_datetime`	string	必須	1人目の生年月日時（計算は日付単位）
`person2_name`	string	必須	2人目の名前
`person2_datetime`	string	必須	2人目の生年月日時（計算は日付単位）
`include_details`	boolean	任意	三九ペアの詳細解釈（恋愛・結婚・質感）を含める。デフォルト: `true`

リクエスト例

{
  "person1_name": "太郎",
  "person1_datetime": "1990-06-15T14:30:00",
  "person2_name": "花子",
  "person2_datetime": "1992-03-20T09:00:00",
  "include_details": true
}

レスポンス例（抜粋）

{
  "person1": {"sukuyo_name": "軫宿"},
  "person2": {"sukuyo_name": "張宿"},
  "compatibility_method": "sanku",
  "compatibility_relations": [
    {"label": "友", "compatibility_score": 75},
    {"label": "親", "compatibility_score": 80}
  ],
  "average_compatibility_score": 77.5,
  "details": {
    "pair": "友親",
    "quality": "温かく安定した結びつき"
  },
  "calculation_time_ms": 0.6
}

宿曜相性検索

POST /api/v1/sukuyo/compatibility/search 5 credits

基準宿から見た27宿の相性を一覧化します。対象宿を指定すれば1件比較、未指定なら全27宿のランキングを返します。

パラメータ

フィールド	型		説明
`base_nakshatra`	string	必須	基準宿（例: `婁宿`）
`target_nakshatra`	string	任意	対象宿。省略時は全27宿を返す
`filter_type`	string	任意	`good` / `bad`。省略時は全件

リクエスト例

{
  "base_nakshatra": "婁宿",
  "filter_type": "good"
}

レスポンス例（抜粋）

{
  "compatibility_method": "sanku",
  "base_nakshatra": "婁宿",
  "results": [
    {
      "target_nakshatra": "胃宿",
      "relationship_label": "栄",
      "scores": {"overall": 86}
    }
  ],
  "summary": {"total_results": 8, "best_3": [/* ... */]}
}

マヤ暦相性

POST /api/v1/mayan/compatibility 5 credits

2人のKINを比較し、オラクル関係（analog/antipode/occult/guide）・音の調和・紋章カラーファミリーの一致・総合相性スコアを返します。

パラメータ

フィールド	型		説明
`date_a`	string	必須	1人目の日付 (YYYY-MM-DD)
`date_b`	string	必須	2人目の日付 (YYYY-MM-DD)
`correlation`	string	任意	`dreamspell`（デフォルト）/ `gmt`

リクエスト例

{
  "date_a": "1990-06-15",
  "date_b": "1992-03-20",
  "correlation": "dreamspell"
}

レスポンス例（抜粋）

{
  "profile_a": {"kin": 68, "tone": {/* ... */}, "seal": {/* ... */}, /* 完全なMayanOutput */},
  "profile_b": {"kin": 143, /* ... */},
  "relationship_type": "analog",
  "tone_harmony": "harmonious",
  "seal_color_match": true,
  "seal_family_match": false,
  "score": 85,
  "reading": "アナログの関係: 互いの使命を支え合う...",
  "calculation_time_ms": 0.8
}

数秘術相性

POST /api/v1/numerology/compatibility 5 credits

二人の Life Path・Soul・Destiny の整合を比較します。生年月日だけなら Life Path ベース、名前まで入れると Soul / Destiny まで含むフル相性を返します。

パラメータ

フィールド	型		説明
`birth_date1`	string	必須	1人目の生年月日 (YYYY-MM-DD)
`birth_date2`	string	必須	2人目の生年月日 (YYYY-MM-DD)
`name1`	string	任意	1人目のフルネーム（ひらがな/カタカナ/ローマ字対応、漢字非対応）
`name2`	string	任意	2人目のフルネーム（ひらがな/カタカナ/ローマ字対応、漢字非対応）

リクエスト例

{
  "birth_date1": "1984-01-08",
  "birth_date2": "1990-05-15",
  "name1": "FUKUMOTO SHINJI",
  "name2": "たなか はなこ"
}

レスポンス例（抜粋）

{
  "person1": {"life_path": 4, "destiny": 11},
  "person2": {"life_path": 3, "destiny": 5},
  "life_path_compatibility": {"level": "good", "score": 4},
  "soul_compatibility": {"level": "excellent", "score": 5},
  "destiny_compatibility": {"level": "neutral", "score": 2},
  "overall": "good",
  "total_score": 11,
  "calculation_time_ms": 0.5
}

トランジット

POST /api/v1/horoscope/transits 10 credits

指定日時のトランジットを計算します。現在または指定時刻の天体位置が出生図の天体に形成するアスペクトを検出し、影響の強さとタイミングを返します。期間内の exact transit timeline は horoscope/transit_events を使ってください。

パラメータ

フィールド	型		説明
`name`	string	必須	対象者の名前
`datetime`	string	必須	出生日時
`latitude/longitude`	number	条件付き必須	`address` / `location` を使わない場合に必須
`address`	string	条件付き必須	`latitude/longitude` または `location` の代替
`location`	string	条件付き必須	`latitude/longitude` または `address` の代替
`transit_date`	string	任意	トランジット日時。オフセット付きISOなら絶対時刻、naiveなら `timezone` の地方時として解釈。デフォルト: 現在時刻
`include_auxiliary_points`	boolean	任意	補助感受点（`natal_points`/`transit_points`）を返すか。デフォルト: `false`
`include_lilith_true`	boolean	任意	`lilith_true` を返すか。旧 `include_true_lilith` 互換
`include_period_analysis`	boolean	任意	月間テーマ、月相、逆行期間、ボイドタイムなどの期間分析を追加計算するか。デフォルト: `false`
`response_profile`	string	任意	`full` / `facts` / `agent`。デフォルト: `full`

transits も narrative 解釈を標準で持たないため、facts は実質 full に近い構造です。token 削減が目的なら agent を使ってください。

natal_angles は出生図の固定値で、transit_date では変わりません。時点依存の角度は transit_angles を参照してください。

デフォルトは高速な現在スナップショットです。themes や月間の月相・逆行・ボイドタイムが必要な場合だけ include_period_analysis=true を指定してください。

リクエスト例

{
  "name": "田中太郎",
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo",
  "transit_date": "2026-03-19",
  "include_period_analysis": false,
  "response_profile": "agent"
}

プログレッション

POST /api/v1/horoscope/progressions 10 credits

セカンダリープログレッション（一日一年法）を計算します。進行した惑星位置と出生図へのアスペクトを返します。

パラメータ

フィールド	型		説明
`name`	string	必須	対象者の名前
`datetime`	string	必須	出生日時
`location`	string	必須	出生地
`progression_date`	string	任意	進行先の日付。デフォルト: 今日
`include_auxiliary_points`	boolean	任意	補助感受点（`progressed_points`）を返すか。デフォルト: `false`
`include_lilith_true`	boolean	任意	`lilith_true` を返すか。旧 `include_true_lilith` 互換

リクエスト例

{
  "name": "田中太郎",
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo",
  "progression_date": "2026-03-19"
}

リターンチャート

POST /api/v1/horoscope/return_chart 5 credits

ソーラーリターン、ルナーリターン、サターンリターン、ジュピターリターンを計算します。指定した天体が出生時の位置に戻る正確な日時とチャートを返します。

パラメータ

フィールド	型		説明
`name`	string	必須	対象者の名前
`datetime`	string	必須	出生日時
`location`	string	必須	出生地
`return_type`	string	必須	`solar` / `lunar` / `saturn` / `jupiter`
`year`	integer	任意	計算対象年。デフォルト: 今年
`include_auxiliary_points`	boolean	任意	補助感受点（Lilith/PoF/Vertex）を返すか。デフォルト: `false`
`include_lilith_true`	boolean	任意	`lilith_true` を返すか。旧 `include_true_lilith` 互換
`response_profile`	string	任意	`full` / `facts` / `agent`。デフォルト: `full`

return_chart は narrative 解釈を標準で持たないため、facts は実質 full に近い構造です。token 削減が目的なら agent を使ってください。

リクエスト例

{
  "name": "田中太郎",
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo",
  "return_type": "solar",
  "year": 2026,
  "response_profile": "agent"
}

イベントチャート

POST /api/v1/horoscope/event_chart 5 credits

出生データを使わず、特定の日時と場所の天空図を返します。datetime は offset-aware ISO 8601 を優先し、naive 値は timezone の地方時として解釈されます。時点の天空図を見たいだけなら、このエンドポイントを使ってください。

パラメータ

フィールド	型		説明
`datetime`	string	必須	イベント日時。オフセット付きISOなら絶対時刻、naive なら `timezone` の地方時として解釈
`latitude/longitude`	number	条件付き必須	`address` / `location` を使わない場合に必須
`address`	string	条件付き必須	`latitude/longitude` または `location` の代替
`location`	string	条件付き必須	`latitude/longitude` または `address` の代替
`timezone`	string	任意	IANA timezone。省略時は location から推定、推定不能なら UTC
`include_houses`	boolean	任意	ASC/MC とハウスカスプを返すか。デフォルト: `true`
`include_nodes`	boolean	任意	ドラゴンヘッド/テイルを返すか。デフォルト: `true`
`planets`	array	任意	計算する天体名。省略時は主要天体

レスポンス

返す主なフィールドは chart_type, event_datetime, event_datetime_utc, timezone, location, angles, houses, planets, moon_phase, precision_info です。

リクエスト例

{
  "datetime": "2026-04-08T18:32:00-04:00",
  "latitude": 38.9072,
  "longitude": -77.0369,
  "timezone": "America/New_York",
  "include_houses": true,
  "include_nodes": true
}

トランジットイベント

POST /api/v1/horoscope/transit_events 10 credits

出生図に対して、指定期間内に起きる exact transit timeline を返します。単一日時のスナップショットは transits、出生データなしのmoment chartは event_chart を使ってください。

パラメータ

フィールド	型		説明
`name`	string	必須	対象者の名前
`datetime`	string	必須	出生日時
`latitude/longitude`	number	条件付き必須	`address` / `location` を使わない場合に必須
`address`	string	条件付き必須	`latitude/longitude` または `location` の代替
`location`	string	条件付き必須	`latitude/longitude` または `address` の代替
`start_date`	string	必須	検索開始日時。オフセット付きISOなら絶対時刻、naiveなら `timezone` の地方時として解釈
`end_date`	string	必須	検索終了日時。最大120日。オフセット付きISOなら絶対時刻、naiveなら `timezone` の地方時として解釈
`planets`	array	任意	探索するトランジット天体。省略時は期間に応じて自動選択
`natal_planets`	array	任意	対象にする出生図天体。省略時は主要天体すべて
`min_intensity`	number	任意	最小強度。0.0〜1.0。デフォルト: `0.0`
`max_events`	integer	任意	返す最大イベント数。デフォルト: `100`、上限: `500`
`response_profile`	string	任意	`full` / `facts` / `agent`。デフォルト: `full`

リクエスト例

{
  "name": "田中太郎",
  "datetime": "1990-06-15T14:30:00",
  "latitude": 38.9072,
  "longitude": -77.0369,
  "timezone": "America/New_York",
  "start_date": "2026-04-01T00:00:00-04:00",
  "end_date": "2026-04-30T23:59:59-04:00",
  "planets": ["mars", "jupiter", "saturn"],
  "natal_planets": ["sun", "moon"],
  "max_events": 50
}

干支

POST /api/v1/kanshi 5 credits

年月日時の四柱干支を計算します。六十干支、十二運、空亡、納音に対応。

パラメータ

フィールド	型		説明
`datetime`	string	必須	日時
`location`	string	任意	場所（地方時補正に使用）
`gender`	string	任意	`male` / `female`（大運計算に使用）

リクエスト例

{
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo",
  "gender": "male"
}

宿曜日運

POST /api/v1/sukuyo/fortune 1 credit

本命宿から見た対象日の三九ラベルと、必要に応じて凌犯期間・六害宿の警告を返します。入力は birth_datetime ですが判定は日付単位です。

パラメータ

フィールド	型		説明
`name`	string	必須	名前
`birth_datetime`	string	必須	生年月日時（計算は日付単位）
`target_date`	string	任意	対象日。省略時は今日
`include_ryohan`	boolean	任意	凌犯期間の情報を含める。デフォルト: `true`
`include_rokugai`	boolean	任意	六害宿の情報を含める。デフォルト: `true`

リクエスト例

{
  "name": "太郎",
  "birth_datetime": "1990-06-15T14:30:00",
  "target_date": "2026-06-30T00:00:00",
  "include_ryohan": true,
  "include_rokugai": true
}

レスポンス例（抜粋）

{
  "birth_sukuyo": {"name_japanese": "軫宿"},
  "target_sukuyo": {"name_japanese": "柳宿"},
  "fortune_method": "sanku",
  "sanku_label": "危",
  "fortune_score": 25,
  "ryohan_period": {"is_in_period": true},
  "rokugai": {"is_rokugai_day": false},
  "warning": "現在凌犯期間中です。特に慎重な行動が必要です。"
}

九星気学

POST /api/v1/kyusei 5 credits

九星気学に基づく本命星・月命星・日命星を判定します。吉方位・相性・運勢ガイダンスのサブエンドポイントも利用可能。

サブエンドポイント

/api/v1/kyusei/directions 吉方位判定

/api/v1/kyusei/compatibility 相性判定

/api/v1/kyusei/guidance 運勢ガイダンス

パラメータ

フィールド	型		説明
`datetime`	string	必須	出生日時
`location`	string	任意	出生地

リクエスト例

{
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo"
}

奇門遁甲

POST /api/v1/qimen 25 credits

奇門遁甲の時盤を計算します。天盤・地盤・八門・九星・八神・十干の配置と吉方位を判定。拆補法に準拠。question を添えると shared compiler / observation sidecar が付与されます。

サブエンドポイント

/api/v1/qimen/matrix 九宮マトリクス形式で取得

パラメータ

フィールド	型		説明
`datetime`	string	必須	日時
`timezone`	string	任意	タイムゾーン。省略時は `Asia/Tokyo`
`chart_type`	string	任意	`hour` / `day` / `month` / `year`
`question`	string	任意	相談文。指定時のみ compiler / observation sidecar を付与

リクエスト例

{
  "datetime": "2026-03-19T10:00:00",
  "timezone": "Asia/Tokyo",
  "chart_type": "hour",
  "question": "新しい事業を始めるのに今は良い時期か"
}

風水

POST /api/v1/fengshui 10 credits

住む人の方位相性・建物のエネルギー分布・年ごとの方位運を統合した風水分析。パラメータの有無で分析範囲を自動決定。方位は度数または方位名（北/南/子/午等）で指定可能。

パラメータ

名前	型	説明
`birth_year`	int	生年（個人の方位相性分析用）
`gender`	string	性別 male/female
`building_year`	int	建築年（建物エネルギー分析用）
`facing_direction`	string	建物の向き（方位名: 北/南/子/午等）
`entrance_direction`	string	玄関の向き（年運分析用）
`target_year`	int	年運の対象年

滴天髄遁甲

POST /api/v1/tekitenzui_qimen 100 credits

出生データから個人の五行プロファイルを生成し、時間帯×方角の吉凶を個人化。万人共通の吉方位を、その人だけの吉方位に変換する。

パラメータ

名前	型	説明
`birth_datetime`	string	出生日時（ISO8601）
`gender`	string	性別 male/female
`target_datetime`	string	方位を見る対象日時
`home_longitude`	float	自宅の経度（自然時計算用）

滴天髄風水

POST /api/v1/tekitenzui_fengshui 100 credits

出生データから個人の五行プロファイルを生成し、風水の方位スコアを個人化。8方位のパーソナライズドランキングを生成。

パラメータ

名前	型	説明
`birth_datetime`	string	出生日時（ISO8601）
`gender`	string	性別 male/female
`building_year`	int	建築年（建物エネルギー分析用）
`facing_direction`	string	建物の向き（方位名）
`entrance_direction`	string	玄関の向き

六壬神課

POST /api/v1/liuren 25 credits

六壬神課の課式を立てます。四課三伝・天将・天盤地盤を計算し、課の種類（賊剋・比用・涉害・遥剋・昴星・伏吟・返吟）を判定します。

パラメータ

フィールド	型		説明
`datetime`	string	必須	日時
`location`	string	任意	場所（月将計算に使用）

リクエスト例

{
  "datetime": "2026-03-19T10:00:00",
  "location": "Tokyo"
}

イレクション

POST /api/v1/horoscope/election 10 credits

イレクショナル占星術に基づき、特定の目的に最適な日時を選択します。結婚、起業、契約などの目的に対応。

パラメータ

フィールド	型		説明
`purpose`	string	必須	目的（例: `marriage`, `business`）
`location`	string	必須	場所
`start_date`	string	必須	検索開始日
`end_date`	string	必須	検索終了日

リクエスト例

{
  "purpose": "business",
  "location": "Tokyo",
  "start_date": "2026-04-01",
  "end_date": "2026-04-30"
}

姓名判断

POST /api/v1/seimei 5 credits

姓名判断による三格（天格・人格・地格）の画数分析を行います。生年月日時と名前を入力し、滴天髄ベースの喜忌と連動した評価を返します。full response では shared compiler / observation sidecar も付与されます。

サブエンドポイント

/api/v1/seimei/suggest 吉名候補の提案

パラメータ

フィールド	型		説明
`datetime`	string	必須	生年月日時（ISO 8601）
`timezone`	string	任意	タイムゾーン。デフォルトは `Asia/Tokyo`
`gender`	string	任意	`male` / `female`
`longitude`	number	任意	経度。自然時計算を正確に行いたい場合に指定
`location`	string	任意	都市名・場所名。補助的な入力として利用
`sei`	string	必須	姓（漢字/かな）
`mei`	string	必須	名（漢字/かな）
`stroke_overrides`	object	任意	文字ごとの画数上書き

入力モード

/api/v1/seimei は sei と mei を受け取って評価を返します。/api/v1/seimei/suggest は mei を持たず、同じ生年月日時条件から吉名候補を提案します。

リクエスト例

{
  "datetime": "1984-01-08T23:27:00+09:00",
  "timezone": "Asia/Tokyo",
  "gender": "male",
  "longitude": 135.5023,
  "sei": "福本",
  "mei": "真士"
}

Agent Integration (GPTs / LLM)

Connect TimeQL to OpenAI GPTs, Claude, or any LLM agent. TimeQL provides L0–L5 structured signals; your agent handles L6 interpretation.

1. Get an API key

Dashboard → API Keys

2. Authentication setup (GPTs)

Auth Type	API Key
API Key	Paste the key from your Dashboard
Auth Type	Custom
Custom Header Name	`X-Api-Key`

3. Generate schema URL

GPTs Actions support up to 30 endpoints per action. Select the endpoints you need below, then import the generated URL in GPTs → Actions → Import from URL.

Select endpoints to include (max 30):

0 / 30 selected

4. System prompt for L6 interpretation

Add the following to your agent's system prompt. This establishes the boundary between TimeQL's computed signals (L0–L5) and the agent's interpretation layer (L6).

You are an interpretation layer on top of TimeQL.

TimeQL boundary:
- L0–L5 (input → symbols → relations → progression) = computed by TimeQL.
  Treat these fields as ground truth. Never invent calculations.
- L6 (interpretation) = your responsibility.
  Transform structured signals into contextual, human-readable insight.

Rules:
1. Always call TimeQL for computation. Do not guess scores or positions.
2. Use "notes" and "reading_note" fields as structured symbolic input (L3),
   not as final narrative. Expand them with context.
3. Clearly separate computed facts from your interpretation.
   e.g. "TimeQL reports Jupiter in house 10 (L2). This suggests..."
4. When multiple systems are queried, report convergence and divergence
   explicitly. Do not cherry-pick agreeing signals.
5. Ask only for the minimum required fields before calling an endpoint.
   - horoscope/natal / bazi / jyotish / ziweidoushu usually need datetime + location
   - horoscope/event_chart needs datetime + location; timezone is strongly recommended for deterministic integrations
   - horoscope/transit_events needs natal datetime + location + bounded start/end range
   - sukuyo uses datetime input but computes by calendar date; no location needed
   - mayan needs date only
   - numerology needs birth_date only; full_name is optional
   - dream needs dream_text first; dream_at and wake_affect are optional
 6. Successful compute responses include query_id, query_family,
    and symbol_summary. Preserve query_id in your app state.
 7. If your app captures explicit context, inner signals, or later outcomes,
    attach them with query_id using:
    - /api/v1/feedback/context
    - /api/v1/signals/inner
    - /api/v1/feedback/outcome
 8. Do not require context or inner_signal before the compute call.
    These are optional sidecar events for later analysis.

Endpoint intent map:
- System: health, updates, capabilities, endpoints, taxonomy, openapi-custom
- Profiles & charts: horoscope/natal, kanshi, bazi, tekitenzui, sanmeigaku, jyotish, ziweidoushu, sukuyo, mayan, numerology
- Compatibility & relationships: horoscope/synastry, horoscope/triple_synastry, horoscope/composite, bazi/compatibility, sanmeigaku/compatibility, kyusei/compatibility, sukuyo/compatibility, sukuyo/compatibility/search, mayan/compatibility, numerology/compatibility
- Timing & moment analysis: horoscope/event_chart, horoscope/transit_events, horoscope/transits, horoscope/progressions, horoscope/return_chart, bazi/fortune, jyotish/gochara, sukuyo/fortune, liuren, horoscope/election
- Directions & environment: kyusei, kyusei/directions, kyusei/guidance, qimen, qimen/matrix, fengshui, tekitenzui_qimen, tekitenzui_fengshui
- Naming: seimei, seimei/suggest
- Latent symbolic: dream
- Observation: feedback/context, signals/inner, feedback/outcome

5. Example: L6 in action

This demonstrates how a GPT agent transforms TimeQL signals into interpretation while maintaining the boundary.

// Agent receives from TimeQL (L0–L5):
{
  "day_master": { "kanji": "辛", "nature": "宝石" },
  "yojin": { "yojin": "木", "yojin_category": "財星" },
  "notes": {
    "personality": "基本性格: 感受性が鋭く美的センスに優れる...",
    "career": "日主適職キーワード: 美意識、感受性、プライド..."
  }
}

// Agent produces (L6 interpretation):
"TimeQL identifies 辛 (polished metal) as day master with 木 (wood)
as the operative element in the wealth category.
The structured notes indicate strong aesthetic sensitivity.

My interpretation: This profile suits creative industries where
refined taste translates into value — design, curation, luxury goods.
The wood element as yojin suggests growth through outward expression
rather than internal accumulation."

Errors

The API returns standard HTTP status codes. Error responses include a JSON body with details.

{
  "error": {
    "code": "invalid_parameter",
    "message": "datetime is required"
  }
}

コード	名前	説明
200	OK	Request succeeded
400	Bad Request	Invalid parameters (missing required fields, format errors)
401	Unauthorized	API key missing or invalid
403	Forbidden	Insufficient credits or plan limit exceeded
429	Too Many Requests	Rate limit exceeded. Check the `Retry-After` header
500	Internal Server Error	Server-side error. Contact support if the issue persists

Rate Limits

Request rates are limited by plan. Exceeding the limit returns a 429 status.

プラン	RPM	日次クォータ	月次クォータ
Free	5	40	1,000
Builder	25	600	15,000
Growth	75	3,600	90,000
Scale	150	12,000	300,000

Response headers

Every response includes headers indicating current usage.

Header	Description
`X-RateLimit-Limit`	Max requests per minute
`X-RateLimit-Remaining`	Remaining requests
`X-RateLimit-Reset`	Seconds until reset
`X-Credits-Remaining`	Remaining credits