{
    "api_version": "2026-03-18",
    "schema_version": "2.3.0",
    "architecture": {
        "mode": "async_task_queue + sync_hourly_endpoint",
        "context_model": {
            "subject": "Натальные неизменяемые данные пользователя (дата\/время\/место рождения).",
            "temporal": "Временные параметры прогноза (target_date\/target_time\/current_location)."
        },
        "result_modes": {
            "legacy": "Если synthesis не запрошен, get_result возвращает классический ответ блока systems.",
            "synthesis_view": "Если synthesis запрошен, get_result поддерживает режимы view=summary|explain|raw."
        }
    },
    "limits": {
        "requests_per_minute": 360,
        "rate_window_seconds": 60,
        "retry_after_seconds": 60,
        "notes": [
            "При превышении лимита API возвращает HTTP 429 и заголовок Retry-After.",
            "Результаты задач хранятся во внутреннем хранилище; срок хранения на уровне публичного API не гарантируется."
        ]
    },
    "authentication": {
        "public_test_key": "655351024",
        "create_task": {
            "api_key_required": true,
            "location": "body.api_key"
        },
        "result_access": {
            "public_key_mode": "Для задач, созданных публичным ключом, get_result\/export_result доступны по request_id.",
            "private_key_mode": "Для задач, созданных приватным ключом, get_result\/export_result требуют тот же ключ через X-API-Key или query api_key.",
            "errors": {
                "401": "Ключ отсутствует или невалиден.",
                "403": "Передан неверный ключ для приватного request_id."
            }
        },
        "headers": {
            "X-API-Key": "Ключ для чтения приватных результатов.",
            "X-Calc-Profile": "Профиль расчёта A\/B."
        },
        "ranking": {
            "description": "Ранг ключа определяет почасовую квоту и стоимость обращения в лимитере.",
            "cost_model": {
                "cost_new": 3,
                "cost_cached": 1
            },
            "ranks": {
                "demiurge": {
                    "limit_per_hour": -1,
                    "is_god": true,
                    "note": "Безлимитный доступ."
                },
                "magus": {
                    "limit_per_hour": 1000,
                    "is_god": false,
                    "note": "Высокая квота."
                },
                "master": {
                    "limit_per_hour": 500,
                    "is_god": false,
                    "note": "Средняя квота."
                },
                "adept": {
                    "limit_per_hour": 100,
                    "is_god": false,
                    "note": "Базовая квота (ранг тестового публичного ключа)."
                }
            }
        }
    },
    "systems": {
        "numerology": "Нумерология: портретные и временные расчёты.",
        "astrology": "Натальная карта на данных эфемерид.",
        "bodygraph": "Дизайн человека: тип, профиль, центры, каналы.",
        "transits": "Транзиты для временного контекста.",
        "forecast": "Прогноз по period_type=day|week|month.",
        "synthesis": "Synthesis++: шкалы, конфликты, breakdown и доменные вклады."
    },
    "numerology": {
        "matrix_destiny": {
            "status": "legacy",
            "description": "Старый компактный блок матрицы судьбы. Контракт сохранён без изменений."
        },
        "matrix_destiny_v2": {
            "system_name": "MatrixDestiny22",
            "version": "2.1.0",
            "reduction_rule": "ladini_digit_sum_22",
            "zero_maps_to": 22,
            "blocks": [
                "basis",
                "canonical",
                "derived_experimental",
                "meta"
            ],
            "canonical": {
                "status": "stable",
                "description": "Канонический слой MatrixDestiny22 v2.1.0. Это основной слой для интеграций, проверки совместимости и машинного анализа.",
                "blocks": {
                    "core": "Базовые якоря, совместимые с legacy matrix_destiny.",
                    "age_nodes": "Возрастные внешние узлы: upper_left_outer, upper_right_outer, lower_right_outer, lower_left_outer.",
                    "generic_programs": "Родовые линии: male_line и female_line.",
                    "channels": "Каналы self_search, socialization, spiritual_exam.",
                    "health_map": "Карта здоровья по отдельной формуле canonical-health-map-1.0.0."
                }
            },
            "derived_experimental": {
                "status": "explain",
                "description": "Производный аналитический слой. Нужен для explain, Synthesis++ и внутренних подсказок, но не является каноническим источником базовых значений.",
                "blocks": [
                    "nodes",
                    "lines",
                    "sectors",
                    "age_cycle",
                    "interpretation",
                    "activation"
                ]
            },
            "forecast_activation_path": "forecast.days[].numerology.matrix_destiny_activation",
            "synthesis_domain": "MATRIX_DESTINY",
            "description": "MatrixDestiny22 v2.1.0 разделяет официальный canonical-слой и производный derived_experimental-слой. Корневые дубли core\/nodes\/lines\/sectors\/age_cycle\/activation удалены из контракта: canonical является каноном, derived_experimental — explain-слоем.",
            "meta": {
                "canonical_mode": "matrix_destiny_22_canonical",
                "compatibility_goal": "common_calculator_consistency",
                "derived_experimental_mode": "non_canonical_explain_layer",
                "experimental_blocks": [
                    "nodes",
                    "lines",
                    "sectors",
                    "age_cycle",
                    "interpretation",
                    "activation"
                ],
                "canonical_blocks": [
                    "core",
                    "age_nodes",
                    "generic_programs",
                    "channels",
                    "health_map"
                ],
                "health_map_formula_version": "canonical-health-map-1.0.0",
                "root_aliases_removed": true
            }
        }
    },
    "synthesis_usage": {
        "workflow": [
            "Шаг 1: create_task с systems, включающим synthesis.",
            "Шаг 2: get_result&view=summary как основной рабочий слой.",
            "Шаг 3: get_result&view=explain для диагностики и объяснения.",
            "Шаг 4: export_result (ndjson\/csv) для BI."
        ],
        "rules": [
            "summary рекомендуется как стабильный интеграционный контракт.",
            "explain рекомендуется для explainability и анализа конфликтов.",
            "raw рекомендуется только для отладки.",
            "Для компактного ответа используйте response.omit_portrait_payload=true."
        ]
    },
    "forecast": {
        "period_types": [
            "day",
            "week",
            "month"
        ],
        "default_period_type": "day",
        "default_target_time": "12:00:00",
        "space_weather_mode": {
            "default": "allow_simulated",
            "values": [
                "allow_simulated",
                "observed_or_estimated",
                "observed_only"
            ]
        },
        "space_weather_data_quality": {
            "values": [
                "observed",
                "estimated",
                "simulated"
            ]
        }
    },
    "hourly_forecast": {
        "action": "get_hourly_forecast",
        "method": "GET",
        "frame": "geocentric",
        "auth": {
            "api_key_required": true,
            "sources": [
                "header:X-API-Key",
                "query:api_key"
            ]
        },
        "query": {
            "required": [
                "date"
            ],
            "location_options": {
                "city": "city (+ optional country) triggers server geo lookup and timezone resolution",
                "coordinates": "lat + lng + timezone"
            },
            "date_aliases": [
                "date",
                "target_date"
            ]
        },
        "range": {
            "start": "local 00:00 requested day",
            "end": "local 00:00 next day inclusive",
            "step_minutes": 60,
            "dst_note": "If timezone has DST shift, number of hourly points may differ from 25 because local calendar hours are preserved."
        },
        "payload": {
            "per_hour": {
                "moon": "Geocentric Moon position: longitude, latitude, sign, speed, retrograde flag (always false for Moon).",
                "planets": "Geocentric positions for Sun, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto.",
                "moon_aspects": "Current major aspects of Moon to planets with separation and delta from exactness.",
                "lunar": "Phase, lunar day, satanic day flags, moonrise correction and void-of-course window."
            }
        },
        "cache": {
            "result_cache": "Dedicated JSON cache by date + lat + lng + timezone.",
            "ephemeris_cache": "Server batch cache of geocentric hourly series from NASA JPL Horizons.",
            "upstream_policy": "Repeated requests for the same geo\/date return from cache without a new upstream fetch."
        }
    },
    "response_options": {
        "omit_portrait_payload": {
            "default": false,
            "description": "Если true, API не включает тяжелые портретные ветки numerology\/astrology\/bodygraph."
        }
    },
    "synthesis": {
        "views": {
            "default": "summary",
            "available": [
                "summary",
                "explain",
                "raw"
            ]
        },
        "export": {
            "action": "export_result",
            "formats": [
                "ndjson",
                "csv"
            ],
            "ndjson_row_types": [
                "summary",
                "domain_component",
                "breakdown_item"
            ]
        },
        "versioning_fields": {
            "schema_version": "export-1.0.0",
            "calculation_version": "ipsm-2.0.0",
            "conflict_rules_version": "conflict-rules-2.0.0",
            "normalization_version": "normalization-2.0.0",
            "weights_hash": "SHA-256 от набора scales\/weights_*"
        },
        "calc_profiles": {
            "default": "A",
            "available": [
                "A",
                "B"
            ],
            "sources": [
                "header:X-Calc-Profile",
                "query:calc_profile",
                "body:calc_profile"
            ]
        }
    },
    "security": {
        "notes": [
            "В ответах API не возвращаются внутренние файловые пути кэша.",
            "run_worker доступен только с localhost или с валидным X-Worker-Token."
        ]
    }
}