{
  "openapi": "3.1.0",
  "info": {
    "title": "WealthTrackr Personal Data API",
    "version": "1.0.0",
    "description": "Read-only REST API for accessing your personal financial data from WealthTrackr. Create and revoke API keys from Settings → Personal API access in the app. Keys are read-only and can be revoked at any time.",
    "contact": {
      "name": "Apercall LLC",
      "url": "https://github.com/apercallc/wealthtrackr",
      "email": "security@apercallc.com"
    }
  },
  "servers": [
    {
      "url": "https://server-production-c1e82.up.railway.app",
      "description": "Production API"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Send your API key (wtk_...) as a Bearer token."
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Send your API key (wtk_...) via the X-API-Key header."
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    },
    {
      "apiKeyHeader": []
    }
  ],
  "paths": {
    "/v1/data/summary": {
      "get": {
        "tags": [
          "data"
        ],
        "summary": "Financial summary",
        "description": "Net worth, asset/liability totals and counts, latest snapshot, and as_of timestamp.",
        "responses": {
          "200": {
            "description": "Financial summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "net_worth": {
                      "type": "number",
                      "description": "Total assets minus total liabilities"
                    },
                    "total_assets": {
                      "type": "number"
                    },
                    "total_liabilities": {
                      "type": "number"
                    },
                    "asset_count": {
                      "type": "integer"
                    },
                    "liability_count": {
                      "type": "integer"
                    },
                    "latest_snapshot": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "month": {
                          "type": "string",
                          "pattern": "^\\d{4}-(0[1-9]|1[0-2])$"
                        },
                        "net_worth": {
                          "type": "number"
                        },
                        "total_assets": {
                          "type": "number"
                        },
                        "total_liabilities": {
                          "type": "number"
                        },
                        "category_breakdown": {
                          "type": "object"
                        },
                        "notes": {
                          "type": "string",
                          "nullable": true
                        },
                        "timestamp": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or revoked API key"
          }
        }
      }
    },
    "/v1/data/items": {
      "get": {
        "tags": [
          "data"
        ],
        "summary": "Account categories and items",
        "description": "Account categories and items, including ownership-adjusted effective_value.",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asset",
                "liability"
              ]
            },
            "description": "Filter account categories by type."
          }
        ],
        "responses": {
          "200": {
            "description": "Categories with items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "categories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "asset",
                              "liability"
                            ]
                          },
                          "total": {
                            "type": "number"
                          },
                          "items": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "label": {
                                  "type": "string"
                                },
                                "value": {
                                  "type": "number"
                                },
                                "ownership_percentage": {
                                  "type": "number"
                                },
                                "effective_value": {
                                  "type": "number",
                                  "description": "value * (ownership_percentage / 100)"
                                },
                                "liquidity_rating": {
                                  "type": "string",
                                  "enum": [
                                    "high",
                                    "medium",
                                    "low"
                                  ]
                                },
                                "notes": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "last_updated": {
                                  "type": "string",
                                  "format": "date-time"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or revoked API key"
          },
          "422": {
            "description": "Invalid query parameter"
          }
        }
      }
    },
    "/v1/data/snapshots": {
      "get": {
        "tags": [
          "data"
        ],
        "summary": "Monthly net-worth snapshots",
        "description": "Monthly net-worth snapshots, newest first.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            },
            "description": "Number of snapshots to return (1–1000). Defaults to all."
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshots list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "snapshots": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "month": {
                            "type": "string",
                            "pattern": "^\\d{4}-(0[1-9]|1[0-2])$"
                          },
                          "net_worth": {
                            "type": "number"
                          },
                          "total_assets": {
                            "type": "number"
                          },
                          "total_liabilities": {
                            "type": "number"
                          },
                          "category_breakdown": {
                            "type": "object"
                          },
                          "notes": {
                            "type": "string",
                            "nullable": true
                          },
                          "timestamp": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or revoked API key"
          }
        }
      }
    },
    "/v1/data/metrics": {
      "get": {
        "tags": [
          "data"
        ],
        "summary": "Monthly financial check-ins",
        "description": "Returns the newest entry in 'latest' and all entries newest-first in 'history'. Credit score and each monthly money metric are independently optional; every supplied value is returned, and a record must contain at least one score or money metric. Calculated fields (debt_to_income_ratio, monthly_cash_flow, savings_rate) are null when their required inputs were not recorded.",
        "responses": {
          "200": {
            "description": "Monthly metrics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "latest": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "month": {
                          "type": "string",
                          "pattern": "^\\d{4}-(0[1-9]|1[0-2])$"
                        },
                        "credit_score": {
                          "type": "integer",
                          "nullable": true,
                          "minimum": 300,
                          "maximum": 850,
                          "description": "Optional credit score; a record may instead contain monthly money metrics."
                        },
                        "monthly_income": {
                          "type": "number",
                          "nullable": true
                        },
                        "monthly_expenses": {
                          "type": "number",
                          "nullable": true
                        },
                        "monthly_debt_payments": {
                          "type": "number",
                          "nullable": true
                        },
                        "monthly_savings": {
                          "type": "number",
                          "nullable": true
                        },
                        "retirement_savings": {
                          "type": "number",
                          "nullable": true
                        },
                        "debt_to_income_ratio": {
                          "type": "number",
                          "nullable": true,
                          "description": "(monthly_debt_payments / monthly_income) * 100, or null"
                        },
                        "monthly_cash_flow": {
                          "type": "number",
                          "nullable": true,
                          "description": "monthly_income - monthly_expenses, or null"
                        },
                        "savings_rate": {
                          "type": "number",
                          "nullable": true,
                          "description": "(monthly_savings / monthly_income) * 100, or null"
                        },
                        "updated_at": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    },
                    "history": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "month": {
                            "type": "string"
                          },
                          "credit_score": {
                            "type": "integer",
                            "nullable": true,
                            "minimum": 300,
                            "maximum": 850
                          },
                          "monthly_income": {
                            "type": "number",
                            "nullable": true
                          },
                          "monthly_expenses": {
                            "type": "number",
                            "nullable": true
                          },
                          "monthly_debt_payments": {
                            "type": "number",
                            "nullable": true
                          },
                          "monthly_savings": {
                            "type": "number",
                            "nullable": true
                          },
                          "retirement_savings": {
                            "type": "number",
                            "nullable": true
                          },
                          "debt_to_income_ratio": {
                            "type": "number",
                            "nullable": true
                          },
                          "monthly_cash_flow": {
                            "type": "number",
                            "nullable": true
                          },
                          "savings_rate": {
                            "type": "number",
                            "nullable": true
                          },
                          "updated_at": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or revoked API key"
          }
        }
      }
    }
  }
}