{
  "endpoint": "/api/garmin/auth/link",
  "method": "POST",
  "description": "Initiates the linking process for a Garmin Connect account using username/password.",
  "request": {
    "headers": {
      "Authorization": "Bearer <token>"
    },
    "body": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "format": "email",
          "description": "Garmin Connect account email."
        },
        "password": {
          "type": "string",
          "description": "Garmin Connect account password."
        }
      },
      "required": ["email", "password"],
      "additionalProperties": false
    }
  },
  "response": {
    "200": {
      "description": "Garmin Connect account linked successfully.",
      "body": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Garmin Connect account linked successfully."
          },
          "garmin_connect_account_id": {
            "type": "string",
            "format": "uuid",
            "description": "ID of the newly linked Garmin Connect account."
          }
        },
        "required": ["message", "garmin_connect_account_id"]
      }
    },
    "400": {
      "description": "Bad Request: Invalid credentials or account already linked.",
      "body": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "string",
            "example": "Invalid Garmin Connect credentials or account already linked."
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized: User not authenticated with the application.",
      "body": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "string",
            "example": "Not authenticated with the application."
          }
        }
      }
    },
    "500": {
      "description": "Internal Server Error: Unexpected error during linking process.",
      "body": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "string",
            "example": "An unexpected error occurred during Garmin account linking."
          }
        }
      }
    }
  }
}