{
  "openapi": "3.1.0",
  "info": {
    "title": "HD Matrix Pro API",
    "description": "Human Design chart calculation and interpretation API. FREE tier — no API key required. Rate limited by IP.",
    "version": "1.0.0",
    "contact": {
      "name": "HD Matrix Pro",
      "url": "https://hdmatrix.pro",
      "email": "info@hdmatrix.pro"
    }
  },
  "servers": [
    {
      "url": "https://hdmatrix.pro",
      "description": "Production server"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "summary": "Calculate Human Design chart",
        "description": "Calculate a complete Human Design bodygraph chart from birth data. Returns type, strategy, authority, profile, definition, cross, centers, channels, gates. FREE tier: 20 requests/hour per IP.",
        "operationId": "calculateChart",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["year", "month", "day", "hour", "minute", "place", "latitude", "longitude"],
                "properties": {
                  "year": { "type": "integer", "example": 1990, "description": "Birth year" },
                  "month": { "type": "integer", "example": 3, "description": "Birth month (1-12)" },
                  "day": { "type": "integer", "example": 15, "description": "Birth day (1-31)" },
                  "hour": { "type": "integer", "example": 14, "description": "Birth hour (0-23)" },
                  "minute": { "type": "integer", "example": 30, "description": "Birth minute (0-59)" },
                  "place": { "type": "string", "example": "Kyiv, Ukraine", "description": "Birth place name" },
                  "latitude": { "type": "number", "example": 50.45, "description": "Birth place latitude" },
                  "longitude": { "type": "number", "example": 30.52, "description": "Birth place longitude" },
                  "gender": { "type": "string", "example": "unspecified", "enum": ["male", "female", "unspecified"], "description": "Optional gender" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Chart calculated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "rateLimit": {
                      "type": "object",
                      "properties": {
                        "tier": { "type": "string", "example": "FREE" },
                        "remaining": { "type": "integer" },
                        "limit": { "type": "integer" },
                        "windowMinutes": { "type": "integer" }
                      }
                    },
                    "chart": {
                      "type": "object",
                      "properties": {
                        "type": { "type": "string", "example": "Manifestor" },
                        "strategy": { "type": "string", "example": "To Inform" },
                        "authority": { "type": "string", "example": "Emotional Authority" },
                        "profile": { "type": "string", "example": "3/5: Martyr Heretic" },
                        "definition": { "type": "string", "example": "Single Definition" },
                        "cross": { "type": "string", "example": "The Right Angle Cross of the Eden (1)" },
                        "signature": { "type": "string", "example": "Peace" },
                        "notSelf": { "type": "string", "example": "Anger" }
                      }
                    },
                    "centers": {
                      "type": "object",
                      "properties": {
                        "defined": { "type": "array", "items": { "type": "string" } },
                        "undefined": { "type": "array", "items": { "type": "string" } }
                      }
                    },
                    "channels": { "type": "array", "items": { "type": "string" } },
                    "gates": {
                      "type": "object",
                      "properties": {
                        "personality": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "planet": { "type": "string" },
                              "gate": { "type": "integer" },
                              "line": { "type": "integer" },
                              "color": { "type": "integer" },
                              "tone": { "type": "integer" },
                              "base": { "type": "integer" }
                            }
                          }
                        },
                        "design": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "planet": { "type": "string" },
                              "gate": { "type": "integer" },
                              "line": { "type": "integer" },
                              "color": { "type": "integer" },
                              "tone": { "type": "integer" },
                              "base": { "type": "integer" }
                            }
                          }
                        }
                      }
                    },
                    "aiSummary": {
                      "type": "object",
                      "description": "Human-readable summary for LLM consumption"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "400": {
            "description": "Invalid request"
          }
        }
      }
    },
    "/api/v1/interpret": {
      "post": {
        "summary": "Get HD element interpretation",
        "description": "Retrieve description text for Human Design elements: types, authorities, profiles, gates, channels, centers, etc. FREE tier: 30 requests/hour per IP.",
        "operationId": "getInterpretation",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["type", "key"],
                "properties": {
                  "type": {
                    "type": "string",
                    "example": "type",
                    "enum": ["type", "type_extended", "authority", "profile", "profile_line", "cross", "cross_quantum", "cross_variant", "cross_type", "gate", "gate_line", "channel", "center_defined", "center_undefined", "planet", "gene_key", "dream_gate", "bg5_role", "bg5_penta", "transit_gate", "phs_diet", "phs_env", "phs_motivation", "phs_view", "cognition", "notself", "signature", "strategy"],
                    "description": "Element type. Call GET /api/v1/interpret/list to discover valid keys per type."
                  },
                  "key": {
                    "type": "string",
                    "example": "Manifestor",
                    "description": "Element key/name"
                  },
                  "locale": {
                    "type": "string",
                    "example": "en",
                    "enum": ["uk", "ru", "en", "fr"],
                    "description": "Language locale (default: en)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Interpretation found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "interpretation": {
                      "type": "object",
                      "properties": {
                        "type": { "type": "string" },
                        "key": { "type": "string" },
                        "locale": { "type": "string" },
                        "name": { "type": "string" },
                        "shortDescription": { "type": "string" },
                        "fullDescription": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Interpretation not found"
          }
        }
      }
    },
    "/api/v1/interpret/list": {
      "get": {
        "summary": "Discover interpretation types and keys",
        "description": "Enumerate available interpretation types (with counts and sample keys), or pass ?type=<type> to list every valid key for that type. Lets agents discover keys instead of guessing. FREE tier: 60 requests/hour per IP.",
        "operationId": "listInterpretations",
        "parameters": [
          { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional element type; returns all keys for it (capped at 400)." },
          { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": ["uk", "ru", "en", "fr"] }, "description": "Language locale (default: en)." }
        ],
        "responses": {
          "200": {
            "description": "Type overview, or key list when ?type is given",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "locale": { "type": "string" },
                    "types": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" }, "sampleKeys": { "type": "array", "items": { "type": "string" } } } } },
                    "keys": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" } } } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/transits": {
      "post": {
        "summary": "Get current transits",
        "description": "Get today's planetary transits for a birth chart. Returns Sun gate/line, Moon gate/line, and active transit gates. FREE tier: 15 requests/hour per IP.",
        "operationId": "getTransits",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["year", "month", "day", "hour", "minute", "place", "latitude", "longitude"],
                "properties": {
                  "year": { "type": "integer", "example": 1990 },
                  "month": { "type": "integer", "example": 3 },
                  "day": { "type": "integer", "example": 15 },
                  "hour": { "type": "integer", "example": 14 },
                  "minute": { "type": "integer", "example": 30 },
                  "place": { "type": "string", "example": "Kyiv, Ukraine" },
                  "latitude": { "type": "number", "example": 50.45 },
                  "longitude": { "type": "number", "example": 30.52 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transits retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "date": { "type": "string", "example": "2026-05-22" },
                    "transits": {
                      "type": "object",
                      "properties": {
                        "sun": { "type": "object" },
                        "moon": { "type": "object" },
                        "activeGates": { "type": "array", "items": { "type": "integer" } },
                        "activeGatesCount": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BirthData": {
        "type": "object",
        "required": ["year", "month", "day", "hour", "minute", "place", "latitude", "longitude"],
        "properties": {
          "year": { "type": "integer", "minimum": 1800, "maximum": 2100, "example": 1990 },
          "month": { "type": "integer", "minimum": 1, "maximum": 12, "example": 3 },
          "day": { "type": "integer", "minimum": 1, "maximum": 31, "example": 15 },
          "hour": { "type": "integer", "minimum": 0, "maximum": 23, "example": 14 },
          "minute": { "type": "integer", "minimum": 0, "maximum": 59, "example": 30 },
          "place": { "type": "string", "example": "Kyiv, Ukraine" },
          "latitude": { "type": "number", "minimum": -90, "maximum": 90, "example": 50.45 },
          "longitude": { "type": "number", "minimum": -180, "maximum": 180, "example": 30.52 },
          "gender": { "type": "string", "enum": ["male", "female", "unspecified"], "default": "unspecified" }
        }
      },
      "GateEntry": {
        "type": "object",
        "properties": {
          "planet": { "type": "string", "example": "Sun" },
          "gate": { "type": "integer", "example": 36 },
          "line": { "type": "integer", "example": 2 },
          "color": { "type": "integer" },
          "tone": { "type": "integer" },
          "base": { "type": "integer" }
        }
      },
      "RateLimit": {
        "type": "object",
        "properties": {
          "tier": { "type": "string", "example": "FREE" },
          "remaining": { "type": "integer" },
          "limit": { "type": "integer" },
          "windowMinutes": { "type": "integer" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "details": { "type": "array", "items": { "type": "string" } }
        }
      }
    }
  }
}