{
  "openapi": "3.1.0",
  "info": {
    "title": "ArcFlow Destiny Matrix API",
    "version": "1.0.0",
    "description": "Public, read-only JSON API for the Destiny Matrix (numerology) calculator.\n\nCalculations are deterministic and need no authentication. The documented contract is the `shape=public` response — pass `&shape=public` to receive it. CORS is open for GET. Rate limit: 60 requests/minute per IP per endpoint."
  },
  "servers": [
    {
      "url": "https://destinymatrixcalc.com"
    }
  ],
  "tags": [
    {
      "name": "matrix",
      "description": "Destiny matrix calculations"
    }
  ],
  "paths": {
    "/api/v1/matrix/personal": {
      "get": {
        "tags": [
          "matrix"
        ],
        "summary": "Calculate a personal destiny matrix",
        "description": "Returns the personal destiny matrix for one date of birth: arcana numbers plus interpretation texts (personality, talents, money, relationships, karmic tail, life purposes).",
        "operationId": "getPersonalMatrix",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": true,
            "description": "Date of birth in DD-MM-YYYY format (YYYY-MM-DD also accepted).",
            "schema": {
              "type": "string",
              "example": "15-05-1990"
            }
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Optional display name.",
            "schema": {
              "type": "string",
              "maxLength": 100,
              "example": "Anna"
            }
          },
          {
            "name": "locale",
            "in": "query",
            "required": false,
            "description": "Content language. Default: ru.",
            "schema": {
              "type": "string",
              "enum": [
                "ru",
                "en",
                "es"
              ],
              "default": "ru"
            }
          },
          {
            "name": "shape",
            "in": "query",
            "required": false,
            "description": "Response contract. `public` returns the clean, stable shape documented here. `legacy` (default) returns the internal frontend shape and may change.",
            "schema": {
              "type": "string",
              "enum": [
                "public",
                "legacy"
              ],
              "default": "legacy"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated matrix (public shape).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "input": {
                      "type": "object",
                      "properties": {
                        "date": {
                          "type": "string",
                          "example": "15-05-1990"
                        },
                        "locale": {
                          "type": "string",
                          "example": "en"
                        },
                        "name": {
                          "type": "string",
                          "example": "Anna"
                        }
                      }
                    },
                    "matrix": {
                      "type": "object",
                      "description": "All matrix points as arcana numbers (1–22), keyed by position.",
                      "additionalProperties": {
                        "type": "integer"
                      },
                      "example": {
                        "A": 6,
                        "B": 5,
                        "C": 1,
                        "D": 12,
                        "E": 6
                      }
                    },
                    "programs": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": {
                            "type": "string",
                            "example": "Paternal lineage"
                          },
                          "description": {
                            "type": "string",
                            "example": "Legacy and power of the father"
                          },
                          "values": {
                            "type": "array",
                            "items": {
                              "type": "integer"
                            },
                            "example": [
                              20,
                              4,
                              6
                            ]
                          }
                        }
                      }
                    },
                    "ageTasks": {
                      "type": "object",
                      "description": "Life-cycle task arcana, keyed by age window."
                    },
                    "health": {
                      "type": "object",
                      "description": "Chakra/health matrix arcana."
                    },
                    "interpretation": {
                      "type": "object",
                      "description": "Named sections, each an arcana + interpretation.",
                      "additionalProperties": {
                        "type": "object",
                        "description": "An arcana mapped to a matrix position, with its interpretation text(s).",
                        "properties": {
                          "code": {
                            "description": "Arcana number 1–22 (or a composite code for the karmic tail)."
                          },
                          "name": {
                            "type": "string",
                            "example": "The Magician"
                          },
                          "value": {
                            "description": "Interpretation: a string or a structured object of texts."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Invalid request parameters"
                    },
                    "details": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "date"
                          },
                          "message": {
                            "type": "string",
                            "example": "Invalid date. Use DD-MM-YYYY, e.g. 15-05-1990."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (60 requests / minute / IP per endpoint).",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds until reset."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Rate limit exceeded. Try again later."
                    },
                    "retryAfter": {
                      "type": "integer",
                      "example": 42
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/matrix/compatibility": {
      "get": {
        "tags": [
          "matrix"
        ],
        "summary": "Calculate compatibility for two dates of birth",
        "description": "Returns the compatibility matrix for two dates: shared arcana numbers plus interpretation texts (union portrait, finances, conflict points, children, growth zones).",
        "operationId": "getCompatibilityMatrix",
        "parameters": [
          {
            "name": "date1",
            "in": "query",
            "required": true,
            "description": "Date of birth in DD-MM-YYYY format (YYYY-MM-DD also accepted).",
            "schema": {
              "type": "string",
              "example": "15-05-1990"
            }
          },
          {
            "name": "date2",
            "in": "query",
            "required": true,
            "description": "Date of birth in DD-MM-YYYY format (YYYY-MM-DD also accepted).",
            "schema": {
              "type": "string",
              "example": "20-08-1995"
            }
          },
          {
            "name": "locale",
            "in": "query",
            "required": false,
            "description": "Content language. Default: ru.",
            "schema": {
              "type": "string",
              "enum": [
                "ru",
                "en",
                "es"
              ],
              "default": "ru"
            }
          },
          {
            "name": "shape",
            "in": "query",
            "required": false,
            "description": "Response contract. `public` returns the clean, stable shape documented here. `legacy` (default) returns the internal frontend shape and may change.",
            "schema": {
              "type": "string",
              "enum": [
                "public",
                "legacy"
              ],
              "default": "legacy"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated compatibility (public shape).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "input": {
                      "type": "object",
                      "properties": {
                        "date1": {
                          "type": "string",
                          "example": "15-05-1990"
                        },
                        "date2": {
                          "type": "string",
                          "example": "20-08-1995"
                        },
                        "locale": {
                          "type": "string",
                          "example": "en"
                        }
                      }
                    },
                    "matrix": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "integer"
                      },
                      "description": "Combined matrix points as arcana numbers (1–22)."
                    },
                    "programs": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "values": {
                            "type": "array",
                            "items": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    },
                    "interpretation": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "object",
                        "description": "An arcana mapped to a matrix position, with its interpretation text(s).",
                        "properties": {
                          "code": {
                            "description": "Arcana number 1–22 (or a composite code for the karmic tail)."
                          },
                          "name": {
                            "type": "string",
                            "example": "The Magician"
                          },
                          "value": {
                            "description": "Interpretation: a string or a structured object of texts."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Invalid request parameters"
                    },
                    "details": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "date"
                          },
                          "message": {
                            "type": "string",
                            "example": "Invalid date. Use DD-MM-YYYY, e.g. 15-05-1990."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (60 requests / minute / IP per endpoint).",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds until reset."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Rate limit exceeded. Try again later."
                    },
                    "retryAfter": {
                      "type": "integer",
                      "example": 42
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/matrix/personal/image": {
      "get": {
        "tags": [
          "matrix"
        ],
        "summary": "Render the personal matrix octagram as an image",
        "description": "Deterministic 1000×1000 octagram (arcana numbers per position). Cacheable forever.",
        "operationId": "getPersonalMatrixImage",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": true,
            "description": "Date of birth in DD-MM-YYYY format (YYYY-MM-DD also accepted).",
            "schema": {
              "type": "string",
              "example": "15-05-1990"
            }
          },
          {
            "name": "locale",
            "in": "query",
            "required": false,
            "description": "Content language. Default: ru.",
            "schema": {
              "type": "string",
              "enum": [
                "ru",
                "en",
                "es"
              ],
              "default": "ru"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "Image format. Default: png.",
            "schema": {
              "type": "string",
              "enum": [
                "svg",
                "png"
              ],
              "default": "png"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The matrix octagram.",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/svg+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Invalid request parameters"
                    },
                    "details": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "date"
                          },
                          "message": {
                            "type": "string",
                            "example": "Invalid date. Use DD-MM-YYYY, e.g. 15-05-1990."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/matrix/compatibility/image": {
      "get": {
        "tags": [
          "matrix"
        ],
        "summary": "Render the compatibility matrix octagram as an image",
        "operationId": "getCompatibilityMatrixImage",
        "parameters": [
          {
            "name": "date1",
            "in": "query",
            "required": true,
            "description": "Date of birth in DD-MM-YYYY format (YYYY-MM-DD also accepted).",
            "schema": {
              "type": "string",
              "example": "15-05-1990"
            }
          },
          {
            "name": "date2",
            "in": "query",
            "required": true,
            "description": "Date of birth in DD-MM-YYYY format (YYYY-MM-DD also accepted).",
            "schema": {
              "type": "string",
              "example": "20-08-1995"
            }
          },
          {
            "name": "locale",
            "in": "query",
            "required": false,
            "description": "Content language. Default: ru.",
            "schema": {
              "type": "string",
              "enum": [
                "ru",
                "en",
                "es"
              ],
              "default": "ru"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "Image format. Default: png.",
            "schema": {
              "type": "string",
              "enum": [
                "svg",
                "png"
              ],
              "default": "png"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The matrix octagram.",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/svg+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Invalid request parameters"
                    },
                    "details": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "date"
                          },
                          "message": {
                            "type": "string",
                            "example": "Invalid date. Use DD-MM-YYYY, e.g. 15-05-1990."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}